Skip to main content

Documentation

This document details best practices for documenting projects and repositories.

Description​

Documentation is an important part of the software development process. It is a best practice to include documentation on the product, project or service you are working on. The following sections explore guidelines for writing documentation, specific structure and what to document.

Rationale​

  • Documentation is important to ensure that repos are maintainable in the future. Engineers can leave and join and knowledge can be lost in this process. Having accurate documentation ensures that all engineers working on a repo can use this to help understand how the repo works and the decisions and designs that led up to this point.
  • Keeping documentation in the repo has many advantages:
    • Does not get misplaced - The documentation sits alongside the code.
    • Accessible for engineers working in the repo.
    • Documentation can be updated and versioned via change control. This allows engineers to update documentation alongside software updates in the same PR and ensures they are checked by other engineers.
  • It is recommended to use GitHub pages with the Just the Docs theme to provide a searchable and UI friendly way for engineers to view documentation whilst also being cost efficient and low on infrastructure effort.
  • Using markdown is a well known documentation language that is very familiar and can be read without it being rendered.

Documentation Guidelines​

  • First capture the Why - A key area of the documentation you write should include the rationale behind certain changes. It is possible to understand the How by reading the code but often the understanding on why something was implemented this way is lost. Why was this dependency chosen? Why do we use ECS over a Lambda here? Why do we store data in RDS ove DynamoDB? What business problem does this entire product solve? etc. Having this insight (primarily through architecture and design documents) will aid future maintainers of the repo.
  • Then capture the How - Providing high level overviews of how the application works can help complement the implementation. Using documentation methods such as diagrams, example payloads, example flows and screenshots can aid the written documentation to help make it clearer for future readers.
  • The documentation should be as clear and concise as possible. The main role of the documentation is to remove ambiguity and provide a basis to aid future engineers. Always have the documentation proof-read by another to ensure that it meets this standard.

Structure & Semantics​

info

This content is mandatory

  • Documentation should be stored in the /docs directory in the repo. There should be 1 /docs directory per monorepo for Github Pages.
  • Documentation files should use markdown (.md)
  • Use GitHub pages to render UI for documentation (see below).
  • Documentation should be clearly navigational and like documents should be grouped together. For example the Architecture & Design section should be separate to Operations & Support section.
  • Diagrams should be saved in the .svg format to allow them to be edited in the future and stored under /assets directories in the relevant section of the documentation structure.
  • Titles should be clear and succinct for easy searching.
  • We should use inclusive language throughout our documentation. We suggest following the Google Developer recommendations.

Using GitHub pages​

info

The following content is recommended.

Add this file under /docs/_config.yml replacing PRODUCT NAME with a suitable name. This sets defaults for GitHub pages to use theming to make pretty documentation that is searchable via a UI.

title: PRODUCT NAME
description: PRODUCT NAME product docs
remote_theme: pmarsceill/just-the-docs
permalink: pretty
back_to_top: true
back_to_top_text: "Back to top"

In the GitHub repo go to Settings > Pages. Enable GitHub pages (setting visibility to private) with the source of the main branch and use the /docs directory. HTTPS should be enforced and a Theme/custom domain are not required.

This will publish a GitHub page for the documentation. It is recommended to copy this URL and add it to the About > Website part of the repo for quick access.

Each markdown page should start with the following header.

---
layout: default
title: Home
nav_order: 1
---

nav_order will dictate where the entry is in the navigation and the tile should be set appropriately. You can create nested children by adding the has_children: true and parent header fields. For more information see examples and read the Just the Docs docs.

What to document​

This content is recommended.

It is important to understand what documentation is useful to have within a repo. The following table provides some common things to document in a repo.

DocumentationDescription
Architecture & DesignArchitecture diagrams and design decision logs are perfectly suited to be within a repo. They provide insight into the software from a high level overview (or granular when needed) and allows engineers to understand the why things were done.
API SchemaHaving documentation on any API endpoints the product has and what they do.
Data SchemaUnderstanding the structure (or reference to code) on how data flows in a service and the schema at rest.
Deployment DetailsProvide details on the CI/CD process for the service. This will allow anyone to deploy the application to production or other environments if required.
Package DetailsIf the repo is a mono-repo you will have many packages within it. It is a good idea to provide an overview of the packages and a brief description of each to aid future understanding on why packages exist and what they do.
Operations / SupportProvide details on how to debug problems, how alarms are triggered (and their notification channels) and how to remedy common issues.
AWS Accounts / ResourcesAny static resources that are used by the application. For example the AWS accounts for each environment and the URLs for web-apps.
Testing GuidesIf the repo has any specific testing requirements this can be captured as documentation.
Repeatable ProceduresSimilar to operations; if there are any standard procedures that must be actioned or repeated (such as a database extract) document how this works such that it can be actioned by any engineer.

Examples​

References & Further Reading​