Documentation Guidelines

Active tickets need to be actively managed and need to be up-to-date. Otherwise, there is a great chance, that a project or service is not manageable. A list prioritizing tickets should not contain more than 10 tickets without reason, but a project can have an unlimited amount of ticket prioritization lists.

The more tickets are located at a project, the more it should be considered, to move these tickets to somewhere else. Move these to a location, where the tickets do not have to be constantly updated for project management and do hinder an overview of the respective project. For instance, if a ticket inside a project is a ticket for fixing a bug inside a module, consider moving the ticket to the module's ticket system, documentation or to write an appropriate TODO inside the affected module's source code. Another target location is an archive project. The project net.splitcells.network.community can be used for such archives and is a good way to avoid noise in the version history and to limit the source code's file size. Generally anything consisting of a list of things without any priority ordering, can be considered an archive.

Tickets should be stored at the location where these are used or matter. It should be easy to figure out which tickets apply to a certain portion of a project. If a person is working on a part of the project in question, relevant tickets should be available with little work.

Tickets can be stored as a comment at the relevant source code location. Every task should start with TODO, which is recognized by many tools. Additional tags can be used in order to signal, which tasks may be ignored under special conditions or may require special care:

  1. ACTIVE: Someone is already working on the marked tag.
  2. TOFIX: This task points to an error.
  3. IDEA: This task may not be a good idea.
  4. HACK: This task marks a code quality issue.