Documentation Guidelines

Documentation links syntax to semantics or represents meta data. A single point of entry should be provided from where every part of the documentation is reachable. Multiple points of additional entries may be provided. It should be possible to render all documentation as one site, were everything can be easily accessed and searched.

Manuals describe the implemented concept and how to use the described things. Thereby, all relevant words with special meaning have to be explained. This includes all words, that are used in implementation. The manual should not describe the API. For simplicity this should only consist of flowing structured text and inlines objects (i.e. images). In Java this is done via CommonMark files.

API documentation describes all things that can be accessed legally. Implementation internals should not be noted here. In Java this is done via Javadoc.

The documentation needs to at least define the goal or the result of the thing in question. Everything needs documentation, but sometimes the name of a thing can be its documentation. Classic documentation can sometimes be replaced by programs (i.e. build script named build.service instead of describing how to build software), but everything needs documentation. Try to minimize program code documentation of micro low level implementation specifics, by encoding the facts in the program code in an understandable way (i.e. try to not document, that a value does not change and instead make the value obviously unchangeable).

Documentation may also contain inspiration emotional content in the form of quotes, metaphors, names, acronyms and haiku and should always relate to the described thing. The additional emotional context provides a different perspective on the semantics of the documented thing. This helps the reader to better understand the project and its usage. The amount of such should be minimal. Currently, the following chapter format is preferred for that: <title><inspirational quote or haiku><content>

Avoid third party inspirational quotes in order to avoid licensing issues. This does not necessarily apply to cases, where the inspirational quotes are injected by an external source dynamically, but licensing needs to be considered in these situations as well.

The history of reasoning, why something was done can be useful as well, in order to understand and avoid problematic alternatives. It can be also used in order to avoid circular development.

Updating the documentation is always a problem. Minimize the amount of documentation. In the best case, the name of a thing is its documentation, but keep in mind that people have vastly different contexts, when they access something, which makes it hard to minimize the document's size. Documenting justifications may also be required in order to omit regressions or developing things in a circle.

If large documentation like a user manual is required, make it a project of its own. Otherwise, documentation and the software development will hinder each other, because of the combined complexity.

Every public API component should not only have a name/id but also have at least an naturally described summary of its functionality in order to merge syntax and semantics. This can be omitted if the name/id is also a natural description.