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).

API documentation describes all things that can be accessed legally. 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.

Obsolete docs are better than no documentation, as it gives hints to the actual current state of the project. Obsolete and therefore false documentation can create more problems than it is worth, so making it obvious, if documentation is obsolete or not is important. Alternatively, make it hard to access obsolete documentation.

From a complexity point of view there are 2 types of documents: One type represent information as an ordered list or a flowing text. The second type, represents info as a tree or a graph. The former one can be viewed as a train of thought, an archive or a linear process. The latter one structures the information, in order to describe a complex thing and i.e. is suitable for project management. Minimize the amount of tree/graph kind of documentation, that need to be kept up to date. Such structures require an enormous amount of energy to be kept up to date or useful.