Effective Documentation

Writing Effective Code Documentation

Last updated by Noel Varanda (opens in a new tab),
UML Diagrams

Effective documentation plays a crucial role in ensuring a streamlined development process, facilitating collaboration, and maintaining code quality within our frontend engineering team. This document outlines the standards and guidelines for documentation across projects, products, and codebases.

Fundamental guidelines

  • Document with purpose

    Document areas that provide value and improve understanding, such as project architecture, key design decisions, and complex business logic.
  • Strive for self-documenting code

    Prioritize writing clean, readable, and expressive code that minimizes the need for excessive comments. Use meaningful variable and function names, adhere to best practices, and follow established style guides.
  • Keep documentation updated

    Regularly review and update documentation to reflect the current state of the project. Remove or update outdated information to maintain accuracy.
  • Use markdown

    Prefer Markdown for general-purpose documentation, as it provides a lightweight and easy-to-read format that supports basic formatting, code snippets, and hyperlinks.
  • Structure documentation

    Organize documentation in a logical and hierarchical manner using sections, subsections, and bullet points for improved readability and navigation.

Choosing the right approach

The choice of documentation approach depends on various factors such as the project's nature, team size, complexity, and the intended audience. Consider the following guidelines when deciding on the appropriate documentation method:

Nature of the project

  • For smaller projects or POC projects, lightweight documentation methods like inline code comments and README files may suffice.
  • Larger projects or complex systems may benefit from more comprehensive documentation approaches like code documentation generators, RFCs, or ADRs.

Team collaboration

  • If the project involves a large team or multiple contributors, using a wiki or knowledge base can facilitate collaboration, knowledge sharing, and centralized documentation management.

Audience and purpose

  • Consider the intended audience of the documentation. Documentation aimed at developers may require more detailed code documentation, while end-user documentation may focus on usage examples, guides, and FAQs.

Project lifecycle

  • Different documentation methods serve different purposes at various stages of the project lifecycle. For example, RFCs are useful during the decision-making phase, while code documentation generators aid in code understanding and maintenance.

Remember, the key to effective documentation is to keep it

Documentation Tools

Code documentation

See our guide on effective code comments for more on this

Code documentation plays a crucial role in enhancing code understanding and maintainability. Here are some recommendations for code documentation:

  • Use JSDoc annotations to describe the purpose, input/output, and usage of code elements.
  • Use inline code comments to provide explanations, clarify complex logic, or document any assumptions or limitations within the code.
  • Follow consistent commenting conventions and guidelines to ensure readability and maintainability.
  • Avoid excessive or redundant comments that don't add value or duplicate the code's functionality.

UML diagrams

Chose between Mermaid (opens in a new tab) and Miro (opens in a new tab) depending on your team's preferences and requirements. Consider the level of version control needed for your UML diagrams and the collaborative aspects of the tool when deciding which option to use.

Remember to document and share your UML diagrams using the chosen tool to ensure clear communication and understanding of your project's architecture.


Mermaid (opens in a new tab) is a text-based diagramming tool. Mermaid allows you to define UML diagrams using a simple syntax directly in Markdown, making it easy to include diagrams in your documentation alongside your code.

One of the advantages of using Mermaid is that the diagrams are stored as text files, which can be committed to a repository. This allows you to track changes to the diagrams over time, just like any other code file. By committing the diagrams, you can see how the architecture of your project evolves and changes over different commits.

Here's an example of how the architecture diagram of a project can change over time through commits:

  1. Initial Commit: feat: add api integration

    graph LR
      A[Frontend] --> B[Backend]
  2. Feature "A" Added: feat: add Feature A integration

    graph LR
      A[Frontend] --> B[Backend]
      A --> C[Feature A]

By committing the Mermaid diagrams, you can easily compare and visualize the changes in your project's architecture over time. This provides valuable insights into how the project has evolved and helps in understanding the architectural decisions made along the way.


If, for any reason, you prefer an alternative to Mermaid, you can also consider using Miro (opens in a new tab). Miro is a collaborative online whiteboard platform that offers powerful diagramming capabilities, including UML diagrams. It provides a visual and intuitive interface for creating UML diagrams, and you can invite team members to collaborate and make changes in real-time.

While Miro does not offer the same version control capabilities as Mermaid with commit tracking, it can be a useful tool for creating and sharing UML diagrams in a collaborative environment. You can export the diagrams as images or PDFs and include them in your documentation alongside the code.

README files

  • Include a comprehensive README file in each project repository to provide an overview of the project, its purpose, and instructions on how to set up and run the project.
  • Cover important details such as prerequisites, installation steps, configuration, usage examples, and troubleshooting tips.
  • Keep the README up-to-date as the project evolves and incorporate any changes or updates.

The file should answer the following questions:

  • What does your project do?

  • Why does your project exist?

  • How do I get started?
  • Where to get help?

Example README file

View a readme template
# <Your-Project-Title>
## Description
Provide a short description explaining the what, why, and how of your project. Use the following questions as a guide:
- What was your motivation?
- Why did you build this project? (Note: the answer is not "Because it was a homework assignment.")
- What problem does it solve?
- What did you learn?
## Table of Contents (Optional)
If your README is long, add a table of contents to make it easy for users to find what they need.
- [Installation](#installation)
- [Usage](#usage)
- [Credits](#credits)
- [License](#license)
## Installation
What are the steps required to install your project? Provide a step-by-step description of how to get the development environment running.
## Usage
Provide instructions and examples for use. Include screenshots as needed.
To add a screenshot, create an `assets/images` folder in your repository and upload your screenshot to it. Then, using the relative filepath, add it to your README using the following syntax:
    ![alt text](assets/images/screenshot.png)
## Credits
List your collaborators, if any, with links to their GitHub profiles.
If you used any third-party assets that require attribution, list the creators with links to their primary web presence in this section.
If you followed tutorials, include links to those here as well.
## License
The last section of a high-quality README file is the license. This lets other developers know what they can and cannot do with your project. If you need help choosing a license, refer to [https://choosealicense.com/](https://choosealicense.com/).
🏆 The previous sections are the bare minimum, and your project will ultimately determine the content of this document. You might also want to consider adding the following sections.
## Badges
Badges aren't necessary, per se, but they demonstrate street cred. Badges let other developers know that you know what you're doing. Check out the badges hosted by [shields.io](https://shields.io/). You may not understand what they all represent now, but you will in time.
## Features
If your project has a lot of features, list them here.
## How to Contribute
If you created an application or package and would like other developers to contribute it, you can include guidelines for how to do so. The [Contributor Covenant](https://www.contributor-covenant.org/) is an industry standard, but you can always write your own if you'd prefer.
## Tests
Go the extra mile and write tests for your application. Then provide examples on how to run them here.

ADR (Architectural decision records)

When documenting architectural decisions, we suggest using ADRs. ADRs provide a standardized format for capturing important decisions made during the development process. You can find an example ADR template here (opens in a new tab).

Here are some resources for writing effective ADRs:

Apart from ADRs, other methods of documenting architectural decisions include design documents, design review meetings, and collaboration tools like Confluence or Notion, where detailed discussions and decisions can be recorded.

RFC (Request for comments)

To propose and discuss major changes or new features, follow the RFC (Request for Comments) process. RFCs provide a structured way to gather feedback, collaborate with team members, and make informed decisions based on consensus. It is recommended to use RFCs for proposing, discussing, and documenting significant architectural decisions, new features, or major changes in the project.

When creating an RFC, consider including the following:

  • Relevant technical details Provide a thorough explanation of the proposed change or feature, including technical specifications, implementation details, and any necessary considerations.
  • Use cases

    Describe the use cases and scenarios where the proposed change or feature would be applicable and beneficial.
  • Potential impact

    Discuss the potential impact the proposed change or feature may have on the project, its dependencies, or existing functionality.
  • Alternative approaches Explore and document any alternative approaches that were considered and explain why the chosen approach is preferred.

You can find an example RFC template here (opens in a new tab) to help you structure your RFC and guide the discussion and decision-making process.

Wiki or knowledge base

To effectively manage project-related documentation, it is recommended to maintain a wiki or knowledge base as a centralized repository. The wiki serves as a valuable resource for storing documentation, guides, tutorials, and best practices related to the project. Here are some guidelines for maintaining a wiki:

  • Categorize and organize information

    Structure the wiki content into clear categories or topics to ensure easy navigation and searchability. This helps users quickly find the information they need.
  • Encourage contributions

    Foster a collaborative environment by encouraging team members to contribute to the wiki. This ensures that knowledge and insights from different perspectives are captured and shared.
  • Keep documentation up-to-date

    As the project evolves, it's important to regularly update the wiki to reflect the latest information and best practices. Assign responsibility to team members or establish a review process to ensure the documentation remains accurate and relevant.

Check out Awesome Github Wikis (opens in a new tab) for examples of well-maintained wikis.

General documentation

For general documentation purposes, we suggest the following tools:

  • Markdown: Markdown is a lightweight markup language that provides a simple and readable format for creating text-based documentation. It supports basic formatting, code snippets, and hyperlinks.

  • GitHub Wiki: GitHub Wiki is a built-in wiki feature provided by GitHub. It allows for collaborative documentation creation and provides an easy way to link and navigate between different pages.

Remember, the choice of documentation tools may vary depending on the specific project requirements. Select the tools that best suit the needs of your project and ensure consistency in their usage across the frontend engineering team.

Keep up to date with any latest changes or announcements by subscribing to the newsletter below.