Documentation Guidelines

The Divio Documentation System classifies documentations into four categories:

Applying this classification, gives each documentation page a clear focus. This gives clarity on what to write about and the language to use when creating the documentation. Documentations, written in this way, tend to be easier to comprehend.

If you have multiple pages discussing a common subject, keep them together as close as possible.

Preferably, you create a common parent to group all the others below. Use that common parent, to introduce the subject (explanation). Also use that introduction to point out other relevant documentations (for example upstream documentations).

Consider your navigation is the table of contents of a book. Do the subjects build upon each other, would they be read from front to back?

Consider to have a consistent page order for the subpages of a subject. Following up on the "reading a book back to front" idea from above, it is suggested using the following order:

Example:

It sometimes can be frustrating to find a relevant piece of documentation. The reason for this is: the right structure does not exist. Depending on the context, a reader might look for a documentation at different locations.

Make it easier for readers to find stuff, by placing the link to a page multiple times in the navigation structure.

Example:

You might know of a documentation similar to yours. You might find help by taking its structure as inspiration:

For example: The APPUiO Cloud User and Technical Documentation and the APPUiO Managed OpenShift Technical documentation was structured by taking the upstream OpenShift documentation as inspiration.

When adding a link to an external page, add ^ at the end of the link text. Two things will happen:

Example: