GitBook / Markdown documentation standards

Owned by Rachel Lawson (Unlicensed)
Last updated: Mar 29, 2023
3 min read

DRAFT - for comment, editing, approval

The layout and structure of a GovStack Building Block is defined in the GitHub building block template repository but this document describes how we use each of the different markdown paragraph types, included content like images and links in a consistent manner.

Gitbook includes great documentation on the paragraph types that may be used in documentation and this document builds upon that with information on how GovStack implements the standards to achieve a high quality result. This resource also explains how to use each of the paragraph types directly in GitHub / Markdown.

When choosing paragraph types, always consider the semantic meaning of the content you are trying to store rather than how you personally want it to look. For example, if you are describing a list of things use a list not a table. Tables are for tabular data. Lists are for lists. Using this approach leads to better accessibility of the final document.

Inline styles - bold, italic etc

Inline styles should be used at a minimum and only to give essential meaning to the document. Avoid their use simply to make something look appealing and never to make something look like a heading or to imply document structure.

If you are trying to draw attention to an important point, consider using a Hint instead.

Headings

Headings should be numbered, manually.

Links may be added from one part of the document to another but always bear in mind the possibility of changes to the structure of the document and, unless absolutely necessary, try to link to the main building block page rather than a deep link into the content. This way, we can always ensure links remain active.

Consider if a hyperlink is actually necessary between parts of the specifications. If we say Information Mediator, people probably know what we’re talking about.

Consider the location of the content and whether it is versioned. Will we make subsequent releases that may change the dependency your link is making? Always link to versioned content where it is available.

If the content you are linking to is in Google Docs and is managed by the GovStack project, it probably needs moving to a better location! If it is to be versioned, it needs moving to GitBook. Otherwise, maybe Confluence or even a blog post is better.

When linking to an external resource,

  1. Consider whether the linked resource may change in the future - is it also a versioned document, like a technical standard? If it is, link to the specific version relevant to GovStack

  2. A good link includes context in the linked text. So, for example, it is better to say “Learn more about overland travel in Morocco” than it is to say “To learn more about overland travel, click here.”

Images

All included images should be included in the GitHub repository so they are not lost. By default, GitBook creates a .gitbook/assets folder to store images uploaded through the UI and we recommend using that location for all images.

Images must include alt text that describes the content of the image.

Diagrams

Diagrams should be created in Mermaid.js syntax where possible and created inline with the content. This means that the “source” of the diagram is always available and differences between versions easily identified.

If the surrounding text describes the content of the diagram, it is okay to say that in the alt text. If not, and the description is long, at a paragraph after the diagram to describe it in full.

GitBook automatically renders Mermaid.js diagrams on publication.

Hints

GitBook expands on the default markdown syntax with Hint boxes. These are excellent for drawing the reader’s attention to important points and are recommended for use. If you are emboldening sections of text in your document, it might be that a hint is actually a better alternative.

Code

Code blocks can and should be added to the documentation using the Markdown code block paragraph type. Identifying the language used helps the reader’s comprehension though automatic syntax highlighting.

OpenAPI

GitBook expands upon Markdown syntax with an interactive OpenAPI viewer. This should be used for all OpenAPI specifications.

To add an OpenAPI specification:

  1. Upload the OpenAPI yaml file to the /api folder of the GitHub repository

  2. In GitBook, use the OpenAPI paragraph type and enter the URL of the raw file on GitHub. To a ccess the raw file on GitHub, click the raw button on the github page for the file. So, for the Workflow building Block, we can find their yaml file at https://github.com/GovStackWorkingGroup/bb-workflow/raw/main/api/swagger.yaml

  3. Select the methods you want to display (probably all of them!)