All Dev Teams Write Documentation. But Do Users Read It?

Jordan Merrick is keenly aware of how difficult it is to get people to read documentation. As a technical writer for tool development platform Retool, his job is to create documentation for users.

"I often joke that users never read documentation," Merrick said. "They're very impatient, they want to be able to try the product as quickly as possible, and documentation is a perceived barrier to that."

Tips for more engaging documentation:

• Make documentation easy to find and read
• Conduct documentation reviews with other team members
• Maintain documentation so it is always up to date
• Don't waste time documenting products that are still in flux
• Include both high-level and low-level documentation
• Make it more interactive
• Include visuals like videos and screenshots
• Embed the importance of documentation into team culture

Documentation Should Be Easy to Find and Read

Storing documentation close to the codebase is a good alternative to obscure shared folders. It makes documentation easier to find and, because developers see it more, they are also more likely to maintain it. Including search functionality and a clear structure that lays out the contents and includes high-level overviews lets users skim around for relevant information.

Code Reviews? Try Documentation Reviews.

Just like with code reviews, it's a good idea to bring other reviewers into the documentation process—ideally early on, even while code is being written. "Don't have one person, or just one subset of people, writing it," said Jon Quigley. "Everybody that's touched by this thing should be part of developing it."

Don't Let Documentation Go Stale

Users are quick to disregard out-of-date documentation. Development teams should have a process around maintaining and updating their documentation. At Deephaven Data Labs, engineers run nightly tests on documentation as well as code. "We really noticed that stale documentation leads to frustration. And that leads to users going elsewhere."

Not All Products Need the Same Level of Documentation

Andreas Nomikos, software engineer at Connectly, thinks it's possible to have too much documentation. "In the product teams, usually the rate of change in the codebase is too fast. Investing a lot of time in documentation doesn't yield a good return on investment because you might be building something and that changes within six months."

Good Documentation Should Tackle the Why

Some people want a high-level overview, while other users are developers looking for low-level guides. "Every user comes into that software with a different background and oftentimes a different goal." Including a "getting started" page can serve as a directory that clarifies the purpose and points toward additional resources.

Make Documentation More Interactive

"Developers, we're people of action, we want to code and we want to make things happen. Why should I go to the documentation and read everything when I can just go code and try it?" Code-coupled documentation that includes both explanatory text and references to the codebase can spruce up an otherwise dull reference document.

Nurture a Culture of Documentation

"If you don't get the culture right, then nothing else you say or put in black and white is going to matter," Quigley said. Managers should promote a culture of documentation by always carving out time during development cycles to update and maintain existing documentation—regardless of the situation.