Documentation Guidelines

Give each page a clear focus

The Divio Documentation System classifies documentations into four categories:

  • learning oriented Tutorials

  • Problem oriented How-to Guides

  • Understanding oriented Explanations

  • Information oriented References

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.

Do not use this classification to inform your navigation structure.

Build navigation around subjects

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

Order subjects in logical order

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?

Antora adds links to the previous and next page.

Keep a consistent order for the subpages of a subject

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:

  • Subject page (explanation)

    • Tutorials

    • How-tos

    • Explanations

    • References

Example:

  • Logging

    • Getting started (a tutorial where a small log generating app gets deployed. The tutorial then teaches how to access the logs of that application).

    • Access application logs (how-to)

    • View logs of several applications at the same time (how-to)

    • Structured logs (working with JSON formatted logs, how-to)

    • The logging system (explanation)

    • Log retention (reference)

Add a page multiple times

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:

  • Supported Infrastructures

    • cloudscale.ch

      • Add a node

  • Machine and Node Management

    • cloudscale.ch

      • Add a node

  • Day two operations

    • cloudscale.ch

      • Add a node

Draw inspiration from others

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

For example: The APPUiO User and Technical Documentation and the 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:

  • The link will be opened in a blank window

  • The link will be marked as an external link (indicated by an icon)

Example:

https://example.com[^]
https://example.com[Example^]