Skip to content
d-centralize handbook

Writing documentation

The main goals for writing documentation within our organization are:

  1. Allowing onboarding of new colleagues.
  2. Providing information to clients on how to accomplish tasks.

Parts of the documentation are written manually. Documentation can contain an auto generated part (for example: extracted docstrings from code).

  1. Easy onboarding means that a new colleague can easily grasp the concepts and architecture of a project upon browsing the GitLab repo. To make this information easy to find and maintain, the main entrypoint for documentation is the README file in the root of the project. Strive for all documentation to be in that file or linked from it.

For new projects the advice would be using Markdown syntax.

  1. The best way to write client documentation differs per project. The main entrypoint is typically its public website. For example, pro6pp.nl has general product information as well as technical information. It contains manually written segments as well as generated/dynamic documentation (coming from an OpenAPI specification served by the API). Examples on how to use the API in several programming languages are also part of it.