Documentation system

What the documentation system covers

This section describes the languages and tools chosen to produce this website, and how they are configured and operated. The starting point is to follow the Docs as code approach to keep source code and documentation close together, and to use standard developer tools to support document writing.

The documentation covers the following users and systems.

Documentation system overview
Figure 1. Documentation system overview

Key roles and subsystems

Editor

An editor can also be a developer, and contributes content sources (text, diagrams). The choice of tools to edit and manage content should be flexible.

Content sources

Implementation-specific, detailed documentation should live close to, or even inside source code or configuration files. Higher-level decisions and architectures can live in separate documentation sections.

Sources are typically spread over multiple locations and repositories, and may cover multiple versions of a part of the documentation.

Publisher

The publisher triggers an update of the website by generating a new version and publishing this version. This may be part of an automated update system.

The publisher also manages the styling of the output via the website generator system. This way, the same content sources could be re-used for different documentation websites.

Website generator

The website generator combines sources from multiple repositories and versions into a single website.

The website can be published as a static website, to any suitable platform. Preferably, it’s also possible to generate other formats of documentation, such as PDF or EPUB.

Twitter LinkedIn Github Gitlab Meetup RSS Miro Trello Zotero Hypothesis