On Usable Documentation

Having no documentation is often less harmful than having inaccurate documentation.

Like code, documentation degrades over time. What was once accurate may now be obsolete. And practices we once ignored might now be part of our daily workflow. Unless maintaining documentation is an intentional process, it will rot, maybe beyond saving.

In this article I’ll outline a few guidelines that worked well for me in the past for keeping the developer documentation usable. They’re certainly not universal, but they are a good starting point for a small team of experienced developers. We’ll skip the philosophical debates and focus on real-world practices that work for small, fast-moving engineering teams – the aim is to get the most value with the least effort. Documentation doesn’t pay the
bills.

1. Keep Documentation in the Codebase

If your documentation is for developers, the natural thing to do is to keep the documentation close to the code. Create a docs/ folder in the project root and add some markdown files to it. Everyone already has a documentation viewer — their code editor. As a cherry on top, GitHub renders markdown files in the browser so you can visually browse the documentation. Add a README.md with a short description to every subfolder to make it easier to navigate on the web.

Greppability is a huge plus — searching for a class name will render both code and documentation results.

I usually read the raw markdown files because most of our articles are text-only, but in case of multimedia, I can view it either using my editor’s markdown preview, or navigate to GitHub.

2. Flat is generally better

Engineers tend to value neatness. It’s very tempting to start developing a complex hierarchy of folders, enumerating all possible domains, adding placeholder folders and articles. The thing is, documentation is meant to be read. If the structure is too complex, the information becomes fragmented and hard to find, even though it’s seemingly well-organized.

When organizing the documentation, ask yourself how would you find this if production was down and finding this information was the only thing that could help.

Another benefit of flatter organization is surfacing “unknown unknowns” — useful insights you wouldn’t have searched for but found by proximity to other information.

Not so good structure:

/docs
    /architecture
        /infrastructure
            servers.md
            linux.md
            dns.md
            cdn.md
        /backend
            django.md
            celery.md
        /frontend
            components.md
/docs
    /architecture
        /infrastructure
            servers.md
            linux.md
            dns.md
            cdn.md
        /backend
            django.md
            celery.md
        /frontend
            components.md
/docs
    /architecture
        /infrastructure
            servers.md
            linux.md
            dns.md
            cdn.md
        /backend
            django.md
            celery.md
        /frontend
            components.md

Enter fullscreen mode Exit fullscreen mode

Better structure:

/docs
    README.md
    local_setup.md
    infrastructure.md
    deployment.md
    troubleshooting.md
/docs
    README.md
    local_setup.md
    infrastructure.md
    deployment.md
    troubleshooting.md
/docs
    README.md
    local_setup.md
    infrastructure.md
    deployment.md
    troubleshooting.md

Enter fullscreen mode Exit fullscreen mode

3. Keep It Company-Specific

Your documentation should contain company-specific notes, and not write in general about engineering concepts. If we have a special way of handling CORS, write about our specifics, do not explain what CORS is. There are plenty of articles on that written by people who know more about it than you.

Not so good article:

CORS stands for Cross-Origin Resource Sharing.
It is a mechanism that allows ...
CORS stands for Cross-Origin Resource Sharing.
It is a mechanism that allows ...
CORS stands for Cross-Origin Resource Sharing.
It is a mechanism that allows ...

Enter fullscreen mode Exit fullscreen mode

Better article:

CORS is handled by `django-cors-headers`.
See `settings.py` for list of allowed origins.
CORS is handled by `django-cors-headers`.
See `settings.py` for list of allowed origins.
CORS is handled by `django-cors-headers`.
See `settings.py` for list of allowed origins.

Enter fullscreen mode Exit fullscreen mode

If it’s really important to understand the concept well, link to an external source, but keep in mind that links rot as well, and you will need to update them periodically. Prefer well-established sources like MDN, Django documentation, etc.

4. Someone Has To Be the Documentation Police

Good documentation is a process, not a one-off task — and every process needs an owner.

Even in small teams, there are people with different priorities. If we’re moving fast, it’s OK to skip writing documentation for a while, but someone needs to keep the documentation debt on their mind, and schedule updates, deprecations and additions. This can be anyone who is willing. Tenured engineers are probably a better choice than engineering managers who are more removed from day to day operations.

5. Continual Improvement

Best test of your documentation is a new person joining the team. They come from a different way of doing things, and haven’t yet got accustomed to “our way”. Their first months in the company should be used to re-evaluate the usefulness and correctness of the documentation.

They might suggest new additions because we’re taking some knowledge as a given. They will quickly catch things that are no longer true because they will be following the steps in the documentation to the letter. It would be a shame to not use this opportunity for improvement.

It’s especially a good idea to make documentation review a part of the onboarding process: tell the new hires it’s one of their first duties to review the documentation and suggest improvements. Make sure to follow-up on their suggestions, providing feedback on acceptance or rejection, and let them implement the changes.

6. Periodic Revision

Very related to previous point, but still different. You will probably not reorganize the documentation because one person found it unclear. But, if it’s a pattern, then you will schedule time for this on the roadmap, and approach it very seriously.

6 or 12 month cadence seems reasonable. Dedicate some time to gather feedback. Take a high-level overview:

• Which articles are rarely used?
• What’s outdated?
• Are any links broken?
• Are any articles too long or unfocused?
• Are we missing any key topics?

Asking publicly in Slack what people think of the current state of the documentation is a good start.

7. Make Documentation a Habit

Unused documentation is a sign of bad documentation.

Propagate the documentation. Link to articles instead of providing the answer directly, this increases the chance of discovering unknown unknowns. If the answer is not in the documentation, then write it down. Encourage your team colleagues to do the same. Build the culture of writing documentation.

When done right, usable documentation is a force multiplier that makes onboarding faster, reduces support noise, and helps everyone move faster with confidence.

原文链接：On Usable Documentation