To ensure everyone is aware of a consistent set of criteria for inclusion of content into the specifications, we define here a series of quality criteria: Think of them as gates that a change must pass through to be acceptable.
Changes should be assessed against these gates at all stages of its development but it is the Commit Lead who is ultimately accountable for accepted changes meeting the criteria defined here.
Links to other GovStack-controlled resources
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.
Links to external resources
When linking to an external resource,
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
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:
Upload the OpenAPI yaml file to the /api folder of the GitHub repository
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
Select the methods you want to display (probably all of them!)
Language
Added content is always in International English