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.
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.
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.
Documentation has to follow a standard structure for consistency across projects. The mandatory sections are the following:
- 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 │ └── ...
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.
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.
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 │ └── ...
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 │ └── ...
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 │ └── ...
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.
- Configure the CI so that it automatically publishes the documentation to the Github Wiki via a Github Action. Find more information about this step here.
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.
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
.github/ | └── wiki/ | ├── Home.md | ├── Getting-started.md | └── assets/ │ └── images/ │ ├── architecture/ │ │ └── authentication-diagram.png │ ├── infrastructure/ | | └── heroku-dyno.png | └── operations/ | └── data-export.png ...
- 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]]
- Adding images normally:
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]]
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]] ...