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.
But for the developers and technical writers who write documentation to help others understand the design, functionality and architecture of applications, the phenomenon can be quite frustrating. They pour countless hours into documenting a product for external or internal users, only to find out that hardly anyone knows it exists. And at the same time, users are asking the very questions you anticipated and addressed in the documentation. It can be demoralizing.
“It’s a phenomenon we’re quite aware of,” Merrick said. He said the challenge always is: “How do we make sure that the documentation is as engaging for users as possible?”
Here are some suggestions for getting people to actually read documentation.
Documentation Should Be Easy to Find and Read
Sometimes teams keep software documentation in an obscure shared folder tucked away on a rarely used server, which compounds the problem. If documentation is hard to find, people are unlikely to go out of their way to read it.
Storing documentation close to the codebase is a good alternative. It makes documentation easier to find and, because developers see it more, they are also more likely to maintain it and keep it up to date.
“I’ve seen a lot of companies put their documentation alongside their code — inside of their repositories or inside of the code files,” said Matt Eland, an instructor at Tech Elevator, a technology bootcamp.
The structure of documentation is also important, according to Heather Natour, head of engineering, seller and B2B at online real-estate platform Opendoor. Documentation that is very long and doesn’t include easy ways for readers to navigate through can turn people away from using it.
Including search functionality in the documentation is helpful, so is having a clear documentation structure that lays out the contents and includes high-level overviews and distinct sections. That way, users can skim around for the information that’s relevant to them instead of being forced to read through the whole thing.
Documentation should have summary sections that state the objective of the document, Natour said. “[That] allows someone to maintain an understanding of where a writer is going and possibly jump around to find what they need.”
Code Reviews? Try Documentation Reviews.
Documentation is usually written after the fact by the same engineers who wrote the code, according to Frédéric Harper, director of developer relations at document parsing company Mindee. And that can be a problem.
“They make assumptions like, ‘We don’t have to go into detail in that part,’ or ‘We don’t even have to explain that part,’” Harper said. “Think about your audience. Treat them like they know nothing about what you’re talking about.”
“Think about your audience. Treat them like they know nothing about what you’re talking about.”
These information blind spots can happen when the documentation writer doesn’t get adequate feedback. Jon Quigley, a software testing engineer at software consulting company Value Transformation, said that 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,” Quigley said. “Everybody that’s touched by this thing should be part of developing it.”
If a systems engineer creates documentation about a system, for example, they should look for input from other engineers who interact with the software in different ways. Not only will that make the documentation more useful to a wider variety of users, it will also improve the design of the software itself.
Don’t Let Documentation Go Stale
Users are quick to disregard out-of-date documentation. Rightly so, because time spent reading outdated documentation is mostly wasted.
“If the terminology has changed or you’re referencing things that don’t really apply anymore, the reader may just discard it completely and not use it,” Natour said.
Development teams should have a process around maintaining and updating their documentation so it doesn’t create another barrier for users, she said.
“We really noticed that stale [documentation] leads to frustration. And that leads to users going elsewhere.”
At data querying company Deephaven Data Labs, engineers actually set up their system to run nightly tests on documentation as well as code, said Amanda Martin, the company’s developer relations engineer. Deephaven creates documentation for external users — who are themselves developers — so the company takes documentation very seriously.
Deephaven’s engineers store their documentation in GitHub along with the codebase and every night tests are run against the code snippet examples in the documentation. That ensures the documentation will never be out of step with the code in their product.
“We really noticed that stale [documentation] leads to frustration. And that leads to users going elsewhere,” Martin said.
Although not all companies have the resources to run tests against their documentation, development teams should still prioritize keeping documentation up to date as much as possible. Developers can make a habit of updating existing documentation after corresponding code changes.
Not All Products Need the Same Level of Documentation
Andreas Nomikos, software engineer at AI messaging platform Connectly, thinks it’s possible to have too much documentation. If the product is still in flux, it might not make sense to spend a lot of time on detailed documentation, he said.
“In the product teams, usually the rate of change in the codebase is too fast,” Nomikos said. “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.”
In those cases, it’s usually a better strategy to use more informal methods of training and onboarding for new developers. Developers who just joined a project can learn by pair programming with more experienced developers and work on simple tasks that introduce them to the codebase. That doesn’t require as much maintenance and time to set up.
If, on the other hand, developers are creating a shared resource used by many other teams at the company, investing in documentation can make more sense, Nomikos said. Infrastructure teams, for example, create products that are used internally and aren’t changed for years at a time. In those cases, developers should put more effort into creating clear and detailed documentation because many users will need to reference the same document for a long time.
Good Documentation Should Tackle the Why
Developers need a variety of documentation styles to suit different users’ needs.
“Every user comes into that software with a different background and oftentimes a different goal,” Martin said.
Some people want a high-level overview of what the software does and how it compares to other tools, while other users are developers looking for low-level guides that list the inputs and outputs of certain functions they are calling. When Eland is using Dotnet’s machine learning library, for instance, he refers to both the low-level technical documentation — what he calls “reference-style documentation” — and the high-level documentation that explains the overall design. If he only used the reference-style documents, he could easily get lost.
“They all look like they have the same level of importance because they’re all on the same list and it’s all alphabetical,” Eland said. “I don’t know which one to drill into first.”
But instead, if he started with reading high-level documentation like a “getting started” page, it could serve as a directory that clarifies the purpose of the project and points him toward additional resources. For these higher-level documents especially, it’s important to capture the why. If users can understand the developers’ vision for their application by reading the documentation, then they will be more likely to understand the peculiarities of specific implementations that may seem strange out of context.
This can even be as simple as listing system metrics — by giving readers an understanding of the capabilities of an application, it can help them build a mental model for what the application can do.
Make Documentation More Interactive
Some of the most effective documentation for developers are interactive, allowing readers to code along to help absorb the information. Just having text can discourage developers from using it.
“Developers, we’re people of action, we want to code and we want to make things happen,” Harper said. “Why should I go to the documentation and read everything when I can just go code and try it?”
Tom Ahi Dror, co-founder of continuous documentation company Swimm, said code-coupled documentation that includes both explanatory text and references to the codebase can spruce up an otherwise dull reference document. “They either explain the code or use pieces of the code as examples.”
“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?”
His company, Swimm, specializes in creating tools that make it easier for developers to link their documentation to the code. Links to detailed technical documentation appear directly within code editors and links to code also appear in the documentation. Developers writing documentation can follow a similar strategy by adding links and snippets of code into the text of the document to make it easier to understand for readers.
At Retool, Merrick said he usually aims to write interactive documentation that can have the user create something simple within five or ten minutes.
“That sense of accomplishment increases engagement and confidence, to the point that the user is excited to learn more — in which case, they are going to be more engaged with the documentation,” he said.
It’s important to choose simple, real-world examples users might actually encounter when creating interactive documentation, he said.
“Building real-world uses of the product is a lot more engaging because users can more easily map their needs to the use case,” Merrick said. He encouraged developers to create interactive exercises like spinning up customer relationship management tools or dashboards.
Take Advantage of Visuals and Videos
Good visuals and videos can also spruce up dry documentation. Developers who write documentation using Markdown can take advantage of the language’s features to embed links and videos and images directly into the documentation file, Eland said.
“A lot of things that could take paragraphs to describe — or you can record a quick GIF or YouTube video,” Eland said. “People see it and are like, ‘Huh, OK, that makes sense.”
Text-based documentation has advantages too, like searchability, but including both visuals and text can be very helpful for people who learn in different ways. Videos and screenshots don’t even take long to create and can actually save developers’ time.
“An engineer in my team did a quick recording of themselves walking through debugging a specific type of issue, it just lowered the barrier to creating and sharing information,” Natour said. “Being able to get the benefits of those kinds of interactions in a reusable, quick video format was really helpful. It just made it more accessible for people to refer back to.”
Nurture a Culture of Documentation
Regardless of how well projects are documented, much of what determines whether documentation is used and maintained comes down to the development culture. This culture can be measured by whether documentation is truly prioritized when deadlines are tight and critical issues crop up that demand attention, according to Quigley.
Teams can set a policy to write requirements documents, have a careful design review process and even do documentation reviews. But if the team disregards those considerations every time a project is under time pressure, then those policies won’t hold up for long.
That’s why managers should promote a culture of documentation by prioritizing documentation and always carving out time during development cycles to update and maintain existing documentation — regardless of the situation.
“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.
