Documentation

Writing high-quality code following strict conventions is great. It is also equally crucial to have technical documentation written down. It keeps track of all technical aspects of the application during the development process. It is also effective for knowledge transfer to other developers or third parties. Successful documentation will make information easily accessible for the squad members and help the new hires learn quickly, saving time, energy, and support costs.

General Best Practices

• Being concise, precise, and correct: use short, simple, clear sentences. A long and complex document can easily have important information glossed over when quickly reading. Technical documentation must also be free of writing mistakes to be taken seriously.

• Keep the target audience in mind: most readers would not know the application as much as the team which works on it does. Therefore, explaining while keeping the audience’s knowledge level in mind is better than making the reader assume.

• Use consistent format and structure: even though the content of each document is different, prefer to format them by following a similar template and structure. It is easier for the audience to predict the content structure and find the information they need.

• Pay attention to the organization: duplicated content and lack of structure can kill technical documentation. If the information is difficult to find then no one will use the documentation.

• Use visual elements extensively: a picture is worth a thousand words. Whenever possible, it is best to visualize rather than try to explain it. An infrastructure chart is usually easier to understand than a long paragraph of text.

• Keep the information up-to-date: there is no point in providing inaccurate or outdated information. Documentation acts as a source of truth, so it should always be current.

Greenfield Development

Learn more about Greenfield Development

Purposes

Documentation on a greenfield project must be written for the following purposes:

• Defining the project’s architecture and design before developers complete the implementation. A Team Lead can efficiently communicate their vision to the team and ensure everyone is on the same page by setting up the code structure and an accompanying documentation page.
• Capturing the project’s architecture and design decisions after the implementation is completed. It is easy to forget the reasons behind a decision when the team is busy implementing the feature. Documentation helps the team to remember the decisions and the reasons behind them.

Continuous Process

Upon setting up a new project, the team must ensure a GitHub Wiki is created alongside each codebase repository so that they can start writing documentation as part of the feature development from day one.

When implementing a feature, chore, or even bug, the documentation must be added in the same branch. The CI pipeline must be configured to automatically publish the documentation to the GitHub Wiki via a GitHub Action.

Check out an example workflow to automate Wiki documentation publishing

Brownfield Development

Learn more about Brownfield Development

Purposes

For a brownfield project, the documentation must be written for the following purposes:

• Capturing the knowledge acquired through the reverse engineering of the project’s codebase. Codebase discovery is time-consuming and expensive. Without documenting the findings, the team will have to repeat the process whenever they need to understand a part of the application.
• Assessing the project’s architecture and design state. Documentation helps the team understand the current state and identify the structured areas and those that need improvement.

Documentation Consolidation

Upon inheriting a project, depending on the level of available documentation, the team must first focus on consolidating the existing resources into a single source of truth. For instance, if the project has a GitHub Wiki, but also uses Confluence, Google Docs, or Notion, the team must consolidate all the information into the GitHub Wiki (ideally) or another single platform, depending on the client team’s preference. The team must not guess or ask each time where to find the information they need.

In the consolidation process, the content and its structure must be cleaned up to match the expected documentation standards of the team. The team must not be afraid to remove or rewrite content that is not up to the expected standards. Taking ownership of the technical documentation is paramount for the project’s success.

Creation of New Documentation

In most cases, many areas of a brownfield project are not documented. The team must then use the following process to add new documentation:

• Ensure a chore is created to work on the documentation of a specific area of the application. Documentation work must be accounted for as part of the team’s velocity.
• Work in documentation-focused branches, e.g., chore/authentication-documentation.
• Submit a PR for each documentation branch to be reviewed.
• On approval, merge the documentation branch into the develop branch.
• Ensure that the CI pipeline is configured to automatically publish the documentation to the Wiki of the project.

Over time, once the team has a single source of truth and has documented all parts of the codebase, the team can start adding new documentation as part of the feature development process. The team must follow the same process as for greenfield development.