Documentation

• 1: Get started
• 2: Writing guide
• 3: Style guide
• 4: Structure overview
• 5: API documentation

1 - Get started

All of Dolittles documentation is open-source and hosted on GitHub.

Add a new repository to the main Documentation repository

This guide teaches you how to add a new repository to the Dolittle documentation structure.

Start by cloning the Documentation repository:

$ git clone https://github.com/dolittle/documentation

Put your documentation in markdown files under the Source/content folder. You can also add images and other assets in the same folder. Please consult the writing guide for more information on how to write documentation.

Writing

All documentation is written in markdown following the GitHub flavor.

Markdown can be written using simple text editors (Pico, Nano, Notepad), but more thorough editors like Visual Studio Code or Sublime Text are highly recommended. VSCode also has a markdown preview feature.

Read the writing guiden and style guide for more information.

2 - Writing guide

This document is meant to be read alongside the style guide to provide concrete examples on formatting the document and syntax of different Hugo shortcodes.

Documentation overview

All Dolittle documentation is generated using Hugo 0.58.3, with the Dot theme.

Writing documentation

Metadata

All files MUST have a metadata header at the top of the file following the Hugo Front Matter format. Some of this metadata gets put into the generated HTML file.

The keywords and title properties are used for searching while the description shows up in the search results.

---
title: About contributing to documentation
description: Learn about how to contribute to documentation
keywords: Contributing
author: dolittle
// for topmost _index.md files add the correct repository property
repository: https://github.com/dolittle/Documentation
weight: 2
---

The main landing pages also have an icon attribute in the Front-Matter. These icons are from the Themify icon pack.

Documentation filenames

All files MUST be lower cased, words MUST be separated with a dash. Example: csharp-coding-styles.md. Hugo also takes care of converting between dashes and underscores as well as lower- and uppercase.

Links

Within the documentation -site

When adding links to other pages inside this site you need to refer to the page file-name without the file extension (.md). Also, you cannot use the “normal markdown” link [text](filename), you need to place the filename inside `{{<ref “filename”>}} - otherwise the link will be broken. For instance, linking to the API documentation is done by adding a markdown link as follows:

[API]({{< ref "api" >}})

Renders to:

API

External resources

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

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

Looks like this:

Dolittle Home

Diagrams / Figures

Hugo supports Mermaid shortcodes to write diagrams. Mermaid SHOULD be favored over using images when possible. Mermaid documentation

flowchart TB
    Understand --> Describe --> Understand
    Describe --> Implement --> Understand
    Implement --> Verify --> Understand
    Verify --> Deploy --> Understand
    Deploy --> Operate --> Understand

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. Also remember to add alt text to all images explaining them for screen readers.

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.

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.

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

To display images use the standard markdown format:

![alt-text](../images/dolittle.png)

Renders to:

Notices

Hugo supports different levels of alerts:

Tip

Use tips for practical, non-essential information.

{{% alert %}}
You can also create ReadModels with the CLI tool.
{{% /alert %}}

Renders to:

Warning

Use warnings for mandatory information that the user needs to know to protect the user from personal and/or data injury.

{{% alert color="warning" %}}
Do not remove `artifacts.json` if you do not know what you're doing.
{{% /alert %}}

Renders to:

3 - Style guide

This document is meant to serve as a guide for writing documentation. It’s not an exhaustive list, but serves as a starting point for conventions and best practices to follow while writing.

Comprehensive

Cover concepts in-full, or not at all. Describe all of the functionality of a product. Do not omit functionality that you regard as irrelevant for the user. Do not write about what is not there yet. Stay in the current.

Conformant

Describe what you see. Use explicit examples to demonstrate how a feature works. Provide instructions rather than descriptions. Present your information in the order that users experience the subject matter.

Avoid future tense (or using the term “will”) whenever possible. For example, future tense (“The screen will display…") does not read as well as the present tense (“The screen displays…"). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system.
Use simple present tense as much as possible. It avoids problems with consequences and time related communications, and is the easiest tense for translation.

Include (some) examples and tutorials in content. Many readers look first towards examples for quick answers, so including them will help save these people time. Try to write examples for the most common use cases, but not for everything.

Tone

Write in a neutral tone. Avoid humor, personal opinions, colloquial language and talking down to your reader. Stay factual, stay technical.

Example: The applet is a handy little screen grabber.
Rewrite: You use the applet to take screenshots.

Use active voice (subject-verb-object sequence) as it makes for more lively, interesting reading. It is more compelling than passive voice and helps to reduce word count. Examples.

Example: The CLI tool creates the boilerplate.
Rewrite: The boilerplate is created by the CLI tool.

Use second person (“you”) when speaking to or about the reader. Authors can refer to themselves in the first person (“I” in single-author articles or “we” in multiple-author articles) but should keep the focus on the reader.

Avoid sexist language. There is no need to identify gender in your instructions.

Formatting

Use bold to emphasize text that is particularly important, bearing in mind that overusing bold reduces its impact and readability.

Use inline code for anything that the reader must type or enter. For methods, classes, variables, code elements, files and folders.

Use italic when introducing a word that you will also define or are using in a special way. (Use rarely, and do not use for slang.)

Hyperlinks should surround the words which describe the link itself. Never use links like “click here” or “this page”.

Use tips for practical, non-essential information.

Use warnings for mandatory information that the user needs to know to protect the user from personal and/or data injury.

Concise

Review your work frequently as you write your document. Ask yourself which words you can take out.

1. Limit each sentence to less than 25 words.
   Example:
   Under normal operating conditions, the kernel does not always immediately write file data to the disks, storing it in a memory buffer and then periodically writing to the disks to speed up operations.

   Rewrite:
   Normally, the kernel stores the data in memory prior to periodically writing the data to the disk.

2. Limit each paragraph to one topic, each sentence to one idea, each procedure step to one action.
   Example:
   The Workspace Switcher applet helps you navigate all of the virtual desktops available on your system. The X Window system, working in hand with a piece of software called a window manager, allows you to create more than one virtual desktop, known as workspaces, to organize your work, with different applications running in each workspace. The Workspace Switcher applet is a navigational tool to get around the various workspaces, providing a miniature road map in the GNOME panel showing all your workspaces and allowing you to switch easily between them.

   Rewrite:
   You can use the Workspace Switcher to add new workspaces to the GNOME Desktop. You can run different applications in each workspace. The Workspace Switcher applet provides a miniature map that shows all of your workspaces. You can use the Workspace Switcher applet to switch between workspaces.

3. Aim for economical expression.
   Omit weak modifiers such as “quite,” “very,” and “extremely.” Avoid weak verbs such as “is,” “are,” “has,” “have,” “do,” “does,” “provide,” and “support.” (Weak modifiers have a diluting effect, and weak verbs require more wordy constructions.) A particularly weak verb construction to avoid is starting a sentence with “There is …” or “There are…")

4. Prefer shorter words over longer alternatives.
   Example: “helps” rather than “facilitates” and “uses” rather than “utilizes.”

5. Use abbreviations as needed.
   Spell out acronyms on first use. Avoid creating new abbreviation as they can confuse rathen than clarify concepts. Do not explain familiar abbreviations.
   Example:
   Dolittle uses Event Driven Architecture (EDA) and Command Query Responsibility Segregation (CQRS) patterns.
   HTML and CSS are not programming languages.

Structure

Move from the known to the unknown, the old to the new, or the familiar to the unexpected. Structure content to help readers identify and skip over concepts which they already understand or see are not relevant to their immediate questions.

Avoid unnecessary subfolders. Don’t create subfolders that only contain a single page. Make the user have access to the pages with as few clicks as possible.

Headings and lists

Headings should be descriptive and concise. Use a level-one heading to start a broad subject area. Level-one headings are typically generic titles, such as Basic Skills, Getting Started, and so on. Use level-two, level-three, and level-four headings to chunk information into easy-to-identify sections. Do not use more than four heading levels.

Use specific titles that summarize the information in the associated sections. Avoid empty headings devoid of technical content such as “Going further,” “Next steps,” “Considerations,” and so on.

Use numbered lists when the entries in the list must follow a sequence. Use unnumbered lists where the entries are of the same importance and do not follow a sequence. Always introduce a list with a sentence or two.

External resources

This document is based on style guides from GNOME, IBM, Red Hat and Write The Docs.

4 - Structure overview

Structure internally

Documentation lives in our Documentation repository’s Source folder. The 2 main pieces of this folder are content and repositories:

• Source/repositories contain submodules to Dolittle repositories. We are moving away from this, please don’t add new submodules.

• Source/content is the folder that Hugo uses to render dolittle.io, making it the root of the pages. It contains documentation and symlinks to each Source/repositories submodules Documentation folder.

Defining folder hierarchy on dolittle.io

To add structure (sub-folders) to the content folder and make these visible, Hugo expects an _index.md inside the subfolders. The _index.md files acts as a landing page for the subfolder and should contain a Front Matter section. This defines the title, description, keywords & relative weighting in its parent tree.

---
title: Page Title
description: A short description of the pages contents
keywords: comma, separated, keywords, to, help, searching
author: authorname
weight: 2
---

5 - API documentation

All public APIs MUST be documented regardless of what language and use-case.

C# XML Comments

All C# files MUST be documented using XML documentation comments.

For inheritance in documentation, you can use the <inheritdoc/> element.

JavaScript

All JavaScript files MUST be documented using JSDoc.