Docs

Internal documentation

We’re an open-source company, and we want to share as much information as possible with the public. This is also true for documentation, and thus this handbook already contains a lot of documentation topics.

However, we also have internal & confidential information, which we can’t share with the public.

For those topics, we’re using our internal docs system, based on Silverbullet. It’s intended for:

• Internal documentation

• Confidential information

• Customer-specific documentation

• Daily notes

• Sprint notes

• …

Docs vs. Handbook

Both, the internal docs, as well as the handbook are intended for documentation purposes.

However, there are clear rules what belong to the handbook:

• It must have a «public character»

• It must be a «high-level» documentation

For all others, especially «techie documentation» & «boring» internal operations stuff, we’re either using the internal docs, and/or Markdown files in GitLab projects.

Important

Always try to make cross-references between the documentation.

For example, if you describe a topic on a high-level in the handbook, but you’ve a more low-level «techie documentation» in the internal docs, or in a Markdown README.md, cross-reference between those documentation sources.

Service documentation

The handbook is our single point of entry, which contains the high-level documentation (i.e. what we use, and why).

The low-level documentation of a service (i.e. how it’s deployed, configured & operated) is stored as Markdown files right next to its source code in its GitLab project. The files follow our documentation files convention:

File	Audience	Content
README.md	Everyone	What the project is, why we have it, and where it’s deployed
docs/USAGE.md	Users	How to use the project, e.g. access, daily tasks, tips & FAQs
docs/MAINTENANCE.md	IT admins	How to configure, update, and test the project
docs/TROUBLESHOOTING.md	IT admins	How to debug the project, and how to fix known problems

Hint

The README.md is the entrypoint, stored in the root of the project, and links to the files in the docs/ directory. Additional, more detailed docs can be stored in the docs/ directory as well, and should be linked from one of the files above.

Note

If a project already provides its docs in the docs/ directory (e.g. Sphinx docs), the usage, maintenance & troubleshooting are integrated as chapters of those docs instead (e.g. docs/usage.rst). The README.md stays in the root of the project and links to them.

Tip

Start with the handbook, and dive into the service documentation when you need the details. To find the service documentation, directly browse GitLab or use Glancelot.