Writing Effective Code Documentation

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

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

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

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

   docs/architecture/api.md

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

2. Feature "A" Added: feat: add Feature A integration

   docs/architecture/api.md

   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.

Miro

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.

Example README file

# <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:
 
    ```md
    ![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
 
![badmath](https://img.shields.io/github/languages/top/lernantino/badmath)
 
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:

• What is an ADR? (opens in a new tab)
• Architecture Decision Records (ADR) Templates (opens in a new tab)

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:

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:

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.