Repository Documentation

Have you ever heard of “documentation debt”? It is that mysterious phenomenon where documentation becomes outdated faster than an avocado on a kitchen counter. But fear not! Today we will explore how to keep documentation fresh, updated, and surprisingly useful, all directly in your repository.

Forget external wikis nobody updates and shared documents that vanish into the cosmic void of the cloud. It is time to put documentation where it belongs: right next to the code it describes.

📚 Why Keep It in the Repository?

Keeping documentation in the repository is like having the instruction manual attached to the remote control: it is always there when you need it, and it updates when you change the batteries. The benefits?

• Automatic versioning (goodbye to “documentation_final_v3_definitive_this_time_really.doc”)
• Code reviews that include documentation (there is no escape)
• Single source of truth (no more excuses like “ah, but that was the old version”)

🗂️ Types of Documentation

Derivations and Dependencies 🔄

    graph TD
    A[API Gateway] --> B[Service A]
    A --> C[Service B]
    B --> D[(Database)]
    C --> D
  

This is not a family tree of microservices, but it helps you understand who talks to whom.

Text Documentation 📝

Manual

The good old handwritten Markdown, useful when you need to explain complex concepts:

1
2
3
4
5
6
7
8
9

# Service Name

## Local Setup
1. Clone the repository
2. Install dependencies: `npm install`
3. Configure environment variables: `cp .env.example .env`

## Architecture
The service uses an event-driven architecture with…

Generated from Code 🤖

With JSDoc you can generate documentation directly from comments:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

/**
 * Handles user authentication
 * @param {string} username - The user's username
 * @param {string} password - The password in plaintext
 * @returns {Promise<User>} Authenticated user object
 * @throws {AuthError} If credentials are invalid
 */
async function authenticateUser(username: string, password: string): Promise<User> {
  // …
}

For TypeScript, you can use TypeDoc:

1

typedoc src/index.ts --out docs

API Documentation 📡

OpenAPI/Swagger is your best friend here. Example:

1
2
3
4
5
6
7
8

openapi: 3.0.0
info:
  title: My Fantastic Service
  version: 1.0.0
paths:
  /magically-works:
    get:
      summary: Endpoint that works by magic

Architectural Diagrams 🏗️

Because an image is worth more than a thousand words (and a thousand meetings):

    C4Context
    Person(user, "User", "Someone who hopes everything works")
    System(sys, "The System", "What should work")
    System_Ext(magic, "Magic", "What makes everything work")
  

🔍 Documentation Validation Tools

📝 Vale: Grammar and Style Checking

Vale is a prose validator that helps you keep a consistent writing style and correct phrasing.

Installation

1

brew install vale

Configuration

Create a .vale.ini file at the root:

1
2
3
4
5

StylesPath = styles
MinAlertLevel = suggestion

[*.md]
BasedOnStyles = proselint, write-good, vale

📋 Markdownlint: Formatting and Consistency

Markdownlint-cli2 ensures your Markdown follows standard conventions and stays consistently formatted.

Installation

1

brew install markdownlint-cli2

Configuration

Create a .markdownlint.json file at the root:

1
2
3
4
5
6
7
8

{
  "default": true,
  "MD013": false,
  "MD033": false,
  "MD041": false,
  "MD024": false,
  "MD046": false
}

🪝 Git Hooks for Automatic Validation

Git hooks let us run checks automatically before every commit.

Configuring Git Hooks

Create the .githooks directory and the pre-commit file:

1
2
3

mkdir .githooks
touch .githooks/pre-commit
chmod +x .githooks/pre-commit

Configure the content of the pre-commit hook:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

#!/bin/sh
FILES=$(git diff --cached --name-only | grep '\.md$')
if [ -n "$FILES" ]; then
    # Vale check
    vale $FILES
    if [ $? -ne 0 ]; then
        echo "❌ The documentation does not pass Vale checks"
        exit 1
    fi
    
    # Markdownlint check
    markdownlint-cli2 $FILES
    if [ $? -ne 0 ]; then
        echo "❌ The documentation does not pass Markdownlint checks"
        exit 1
    fi
fi

Activate the hooks:

1

git config core.hooksPath .githooks

🚀 Automation Is the Key

Integrate documentation validation into your CI:

1
2
3
4
5
6

documentation:
  script:
    - vale content/**/*.md
    - markdownlint-cli2 "content/**/*.md"
  only:
    - merge_requests

Because documentation is like code: if you do not test it, you cannot trust it.

🎭 Best Practices (or “How Not to Annoy Your Colleagues”)

Update Alongside the Code 📝

• If you change a feature, update its documentation
• If you deprecate something, document it (do not leave traps)

Keep It DRY 🌵

• Use cross-references
• Centralize common information
• Automate generation where possible

Clear Structure 🗂️

• README.md in every important directory
• Table of contents for large repositories
• Links between related documents

💡 Conclusion

Documentation in the repository is not just a best practice; it is an act of kindness toward your future self and your colleagues. And remember: “Code says what it does, documentation says why it does it” (and sometimes how it manages to do it, when the code is especially cryptic).