Documentation is an Engineering Problem

We spend a lot of time talking about code quality, testing strategies, and CI/CD pipelines. These are all crucial, and rightly so. But there’s another aspect of software development that often gets treated as an afterthought, something we do “when we have time”: documentation.

I’m here to tell you that documentation is not a chore; it’s an engineering problem. And like any good engineering problem, it deserves a structured, thoughtful approach.

Why Treat Docs Like Code?

Think about it. When was the last time you saw a sprawling, messy codebase that was easy to work with? Probably never. The same applies to documentation. Poorly organized, outdated, or incomplete docs are a developer’s nightmare. They slow down onboarding, frustrate users, and lead to more support requests. It’s a technical debt that keeps on giving.

When we treat documentation as code, we bring the rigor of software engineering to it. This means:

Version Control: Docs should live alongside the code they describe. Use Git, track changes, review pull requests for documentation updates just like you do for code. This ensures docs stay in sync with the actual implementation.
Automated Checks: Can we lint our documentation? Can we check for broken links automatically? Absolutely. Tools like Vale or markdownlint can enforce style guides and catch common errors. Continuous Integration can run these checks before merging.
Clear Ownership: Who is responsible for updating the docs? In a code-as-documentation mindset, the engineers writing the code own the docs. This isn’t to say we can’t have dedicated technical writers, but the primary responsibility for accuracy should lie with the implementers.
Testing: Yes, testing documentation. This could mean writing integration tests that verify code examples actually work, or using tools that scan your docs for API changes. If your documentation has code snippets, make sure those snippets are correct.

Practical Steps

So, how do we actually do this?

Integrate Docs into Your Workflow: Make documentation updates a mandatory part of any feature or bug fix. Add it to your Definition of Done. If a feature isn’t documented, it’s not considered complete.
Choose the Right Tools: Static site generators like Docusaurus, MkDocs, or even just plain Markdown files in a repository are good starting points. Find tools that integrate well with your development process and make writing easy.
Establish a Style Guide: Just like you have coding style guides, have a documentation style guide. What’s the tone? How should code examples be formatted? What kind of information should be included in API references? This ensures consistency.
Automate Where Possible: Set up CI pipelines to build and deploy your documentation automatically whenever changes are merged. Use linters and link checkers.
Document the “Why,” Not Just the “How”: Code tells you how to do something. Documentation should explain why you’re doing it that way, the decisions made, and the context. This is invaluable for future developers trying to understand or modify the system.

Example: Documenting an API Endpoint

Let’s say you have a simple API endpoint:

1
// POST /users
2
// Creates a new user
3
app.post('/users', (req, res) => {
4
  const { name, email } = req.body;
5
  // Basic validation
6
  if (!name || !email) {
7
    return res.status(400).json({ message: 'Name and email are required' });
8
  }
9

10
  // In a real app, you'd interact with a database here
11
  const newUser = { id: Date.now(), name, email };
12
  console.log('New user created:', newUser);
13

14
  res.status(201).json(newUser);
15
});

A good documentation entry would go beyond just showing this code. It would look something like this (in Markdown):

1
### Create User
2

3
`POST /users`
4

5
Creates a new user record in the system.
6

7
**Request Body:**
8

9
```json
10
{
11
  "name": "string",
12
  "email": "string"
13
}

Example Request:

1
curl -X POST \
2
  http://localhost:3000/users \
3
  -H 'Content-Type: application/json' \
4
  -d '{
5
    "name": "Jane Doe",
6
    "email": "[email protected]"
7
  }'

Responses:

201 Created: User successfully created.

1
{
2
  "id": 1678886400000,
3
  "name": "Jane Doe",
4
  "email": "[email protected]"
5
}

400 Bad Request: Missing required fields.

1
{
2
  "message": "Name and email are required"
3
}

Purpose: This endpoint is essential for onboarding new users into the application, allowing them to register and gain access to personalized features.

1
Notice how it includes the `curl` example, response codes, and example payloads. It also adds a brief sentence about the *purpose*, adding context that the code alone doesn't provide.
2

3
### The Payoff
4

5
Investing in documentation as an engineering problem pays dividends. It leads to more robust, maintainable software, happier developers, and ultimately, better products. Let's stop treating docs as an afterthought and start building them as an integral part of our engineering practice. Your future self, and your team, will thank you.