Writing documentation

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Process

All Dolittle documentation is generated using Hugo. It basically works with GitHub flavored markdown and turns this into HTML pages that we then host. The documentation sits separated into the repository it belongs to and is expected to be in a folder called Documentation inside at the root of the repository. Documentation is updated whenever a pull request is approved. This will then automatically trigger Hugo to build and re-render the pages.

This documentation documenting the documentation process is also adhering to this and as an example you can find it here.

Theme

The documentation is using a fork of a theme called DocDock. We’re adhering to the guidelines and documentation of the theme in combination with Hugos guidelines. Get familiar with the structure and requirements and all the [shortcodes] supported by both Hugo and the theme.

Metadata

All files MUST have a metadata header at the top of the file following the following format:

---
title: About contributing to documentation
description: Learn about how to contribute to documentation
keywords: Contributing
---

Some of this metadata gets put into the generated HTML file and some of it is used for indexing and other purposes and for future expansion.

Documentation filenames

All files MUST be lower cased, words MUST be separated with underscore. Example: csharp_coding_styles.md.

When adding links to other pages you MUST NOT include the file extension .md - otherwise the link will be broken. For instance, linking to the API documentation is done by adding a markdown link as follows:

[API](./api)

Even though the file is actually called api.md.

External resources

Linking to external resources, is done in the standard Markdown way:

[Dolittle Home](https://github.com/dolittle/home)

Cross Repositories

In order to cross-reference content that sits in a different repository…..

More details coming soon

Diagrams / Figures

All diagrams and figures SHOULD be done using the Mermaid shortcode. Mermaid has more features and is well documented here.

Some diagrams/figures might not be possible to do using Mermaid, these can then be images. Beware however how you create these images and make sure they comply with the look and feel.

Images

All images should be kept close to the markdown file using it. To make sure the folders aren’t getting cluttered and to have some structure, put images in a images folder.

<repository root>
└── Documentation
    └── MyArea
        └── [markdown files]
            └── images
                [image files]

The URL to the image needs to be fully qualified, typically pointing to the GitHub URL. This is something being worked on and registered as an issue here.

Read more here

Images should not have backgrounds that assume the background of the site, instead you SHOULD be using file formats with support for transparency such as png.

Writing

All documentation is written in markdown following the GitHub flavor. Markdown can be written using the simplest of editors (Pico, Nano, Notepad), but there are editors out there that gives great value and guides you through giving you feedback on errors. Editors like Visual Studio Code and Sublime Text comes highly recommended. VSCode has for instance a markdown preview feature.