GovStack Quality Criteria

Owned by Rachel Lawson (Unlicensed)
Last updated: Oct 09, 2023
3 min read

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,

  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.

Image alt text and captions

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.

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.

Text styles, such as bold and italic

Consider why you are styling the text - what is the semantic meaning of the styling?

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.

The GitBook OpenAPI paragraph type should be used to point to OpenAPI definitions, stored in yaml format in the /api folder of the GitHub repository, using the full url to the yaml file in the correct branch for the release. So, for example in Payments BB, we would see the development pages pointing to https://github.com/GovStackWorkingGroup/bb-payments/raw/main/api/Prepaymentvalidation.yaml and, when published in the 1.0 release, the link is updated to https://github.com/GovStackWorkingGroup/bb-payments/raw/1.0-QA/api/Prepaymentvalidation.yaml

Language

Added content is always in International English