Documentation rots because nobody owns it, not because the tooling is wrong. These are the habits that keep a body of docs alive, and the ones that only look like progress.

Start with the reader, not the tool

Most documentation projects open with a platform argument. That is the wrong end of the problem. Before anyone compares static site generators, find out who got stuck, what they were trying to finish, and the exact line where they gave up.

Give every page an owner

A page with no owner rots — not immediately, and not visibly, but steadily. The fix is unglamorous. Put a name against each page, review the list once a quarter, and let people hand pages over when they change teams.

Write the failure cases down

The happy path is the easy half. What actually costs someone an afternoon is the error nobody wrote down, so record the failure mode next to the instruction that avoids it.

Keep the examples runnable

An example that no longer runs is worse than no example, because it still looks authoritative. Put the snippets under test if the stack allows it, and delete them if it does not.

Prune more than you add

Every page you keep is a page somebody maintains. Deleting a stale guide is a contribution and should be treated as one in review.

Measure the questions, not the pageviews

Traffic tells you what people found. The support queue tells you what they did not. The second list is the roadmap.

Conclusion

Ownership beats tooling every time. Pick the owners first, then argue about the platform.

Leave a Reply

Your email address will not be published. Required fields are marked *