Why Your Documentation Sucks

I want to talk about a thread on Hacker News titled The tree-based approach to organizing documentation sucks (worldofbs.com). In the article the author laments the standard tree based way of organizing documentation and instead recommends using a system closer to Wikipedia. Where documentation is organized using the graph approach.

I come across articles like these often. People complaining developer documentation sucks, it’s hard to navigate and often not maintained. Guess what, they are right. There are ways to combat poor documentation. And only using one system of organization is not the answer.

Hire a Writer

Read that heading again, HIRE A WRITER. You can automate everything to hell and back. But a writer is going to make sure it’s good. A technical writer will:

• Research your users
• Figure out the paths users need to take to make the most of the product
• Organize the documentation site in a way that best serves your users
• Write tutorials, explanations and other content that can’t be automated
• Maintain consistency through the documentation
• Have a system in place for writing new documentation and keeping existing content up to date
• Determine the best tool for the job. Static site generator, Confluence, etc.
• Solicit feedback to determine if the documentation is working

A technical writer isn’t a magician. They still need the support of those who write the code.

Make Documentation Part of Your Workflow

Now that you have a writer, please don’t ignore them, then demand miracles. Make documentation a requirement of release. If you’re an engineer or part of the product team, work out a way to include your technical writer. The writer will need:

• To know about new features
• Have engineers available to answer questions, assist with making code samples and other work
• Be invited to sprints
• Notify them of changes to existing features

Invest

You need to invest money in documentation. Good documentation costs money to create, develop and maintain. Many companies only think of documentation as something to do after. Creating a developer culture where documentation is treated as part of the work and not something to dread goes a long way in making documentation great.

This is not an exhaustive list. I could go on and on about building a good documentation culture and team. I hope the points listed here give you pause, every time you read an article about how much documentation sucks.

Finally, using folders (tree) is a valid way of maintaining documentation, just like the graph approach. Both systems will fail if there isn’t someone there to steer the ship.

For more, join Write the Docs and follow https://idratherbewriting.com/.

Todays cover illustration by Karthik Srinivas.