Github Wiki πŸ“–

Hero image for Github Wiki πŸ“–

Unlike regular documentation created by the Product Managers, Github Wiki documentation aims to describe the application in as granular detail as possible. The goal is to express the application targeted towards developers in an easily accessible single source of truth.

Purpose

The reason we write in the Github Wiki is to aid the onboarding process of new developers and decrease the amount of β€œgotchas.”

A standard squad rotation takes up to a month to fully onboard a developer. Writing this technical documentation allows making the rotation process efficient and repeatable thus yields a high return over investment.

This technical documentation also saves time during project handovers and increase the value of the product we deliver to our clients.

Time allocation

Whenever completing an epic or sizable feature, be sure to allocate some time to write documentation.

There are other cases like when adding a third-party service or cron job that requires explanation, but that is on a case-by-case basis. Ultimately, all details worth explaining in terms of the application functionalities would be in the Github Wiki.

Organization

Documentation has to follow a standard structure for consistency across projects. The mandatory sections are the following:

  • Home
  • Getting Started
  • Architecture Section
  • Infrastructure Section
  • Operations Section

Below is an example of what it could contain:

β”œβ”€β”€ Home
β”œβ”€β”€ Getting Started / Project Setup
β”œβ”€β”€ Architecture
β”‚    β”œβ”€β”€ Authentication Flow
β”‚    β”œβ”€β”€ Administration
β”‚    └── ...
β”œβ”€β”€ Infrastructure
β”‚    β”œβ”€β”€ Cron Jobs
β”‚    β”œβ”€β”€ Deployment Procedure
β”‚    β”œβ”€β”€ Environment Variables
β”‚    └── ...
β”œβ”€β”€ Operations
β”‚    β”œβ”€β”€ Debugging
β”‚    β”œβ”€β”€ Testing
β”‚    └── ...

Home

This section contains a general summary of the project and background information about the application. It also briefly explains any specific terminology used in the application.

For example:

Home Wiki Example

Getting Started

More technical project setup information is in this section. This section comprises of:

  • Environment version requirements
  • Prior tooling required
  • Any information that helps setting up the development environment in a usable state. (E.g. Inserting test accounts, generating required secret keys.)

Usually, the format of this section is consistent with other projects.

Architecture

This section contains any Architecture Decision References (ADRs) and explanations of the high-level application flow.

All sub-headings are specific application flows on the application. These sections are where we place all application features and functionalities.

# Examples
β”œβ”€β”€ Architecture (ADRs and high-level diagrams)
β”‚    β”œβ”€β”€ Registration
β”‚    β”œβ”€β”€ Payment Flow
β”‚    β”œβ”€β”€ Admin Section
β”‚    └── ...

Infrastructure

This section involves any prior application setup that requires explanation, such as CI/CD, secrets management, localization, and ongoing cron jobs.

It is primarily to help developers understand the proper setup and deployment of the application.

# Examples
β”œβ”€β”€ Infrastructure (Cloud/Hosting Infrastructure Diagram)
β”‚    β”œβ”€β”€ Ongoing Cron Jobs
β”‚    β”œβ”€β”€ Deployment Procedure
β”‚    β”œβ”€β”€ Environment Variables
β”‚    β”œβ”€β”€ Localization
β”‚    β”œβ”€β”€ Secret Management
β”‚    └── ...

Operations

Any activity that will ensure the smooth running or maintenance of the application goes here.

This section gives an overview of administrative tasks that are pertinent to the running of the application. Subheadings usually contain helpful debugging procedures, testing helpers, or mock data used in tests.

# Examples
β”œβ”€β”€ Operations (Overview of important tasks)
β”‚    β”œβ”€β”€ Running Tests
β”‚    β”œβ”€β”€ Running Docker tests on the CI
β”‚    β”œβ”€β”€ Automated Code Review Setup
β”‚    β”œβ”€β”€ Debugging
β”‚    β”œβ”€β”€ Testing
β”‚    └── ...

An example wiki we’ve made can be found here.

Merging Documentation

Creating New Documentation

  • After merging a feature branch, work on the documentation branch.
  • Submit a PR for the documentation branch to be reviewed.
  • On approval, merge the documentation branch to development.
  • On the CI, it will automatically publish to the Github Wiki via Github Action. We can find more information about the Github Action used here.

Documentation Review

Reviewing documentation is similar to regular pull requests. There are other guidelines we should follow to meet standards.

  • Ensure all content is formally written in the active voice.
  • Pay extra attention to grammar and punctuation. Use a grammar-checker such as Grammarly.
  • Ensure the target audience of the documentation is aimed towards developers with a limited understanding of the project.
  • As there are many opinions on conveying the same message, aim to resolve discussions quickly.

Asset Management

Adding Images

By default, the text editor for Github wiki does not support image uploads and would require hosting images elsewhere. But Github wikis are regular git repositories, so it is possible to add assets by:

  • Clone the repository to your local machine

  • Add all images under the assets/images/ directory

.github/
|  └── wiki/
|       β”œβ”€β”€ Home.md
|       β”œβ”€β”€ Getting-started.md
|       └── assets/
β”‚            └── images/
β”‚                 β”œβ”€β”€ architecture/
β”‚                 β”‚     └── authentication-diagram.png
β”‚                 β”œβ”€β”€ infrastructure/
|                 |     └── heroku-dyno.png
|                 └── operations/
|                       └── data-export.png
...

To keep things organized, replicate the content structure of the markdown files inside the images directory as well.

  • We can then link images inside the content using a relative URL.
    • Adding images normally:
      ![Heroku Dyno Overview](assets/images/infrastructure/heroku-dyno.png)
      
    • Adding with a set width/height:
      [[assets/images/infrastructure/heroku-dyno.png|alt="Heroku Dyno Overview"|height=210px|width=210px]]
      

Use SVG image format wherever possible as they scale well and are easier to see in large infrastructure/architecture diagrams. Lucid chart supports exporting in SVGs. πŸ“ˆ

Referencing Internal Pages

Use one of the following syntaxes to link to other pages within the wiki. There is no need for the absolute path.

  • For example: given a file name Automated-code-review.md, it can be linked to as:
    [[Automated code review]]
    

We can also use a different title for the link.

  • For example: given a file name Scale-in-out-manually.md, a link can be created with a freely chosen title to refer to that page as:
    [[Scale ECS cluster in/out manually|Scale in out manually]]
    

Customized Sidebars

The default sidebar of Github is a flat list of all pages in alphabetical order. We recommend using a custom sidebar to add a visual hierarchy to documentation for easier reference.

Use the headings in our documentation organization in the _Sidebar.md. When adding a new page, be sure to link the page as a link in the Sidebar under the correct section.

A typical sidebar follows our organization structure as follows:

## Table of Contents

* [[Home]]
* [[Getting Started]]

## Architecture

* [[Authentication Flow]]
* [[Administration]]
...

## Infrastructure

* [[Cron Jobs]]
* [[Deployment Procedure]]
* [[Environment Variables]]
...

## Operations

* [[Debugging]]
* [[Testing]]
...