Documentation should be more than just a formality.
Unfortunately, it often gets relegated to that status, despite its massive potential to be a vital primary source of information for developers who want to interact with a software product.
And when the documentation is seen as just a box to tick and forget, mistakes can happen.
They can lead to confusion, wasted time, and more problems down the line for developers who use the documentation.
In this article, we’ll reveal six documentation mistakes that developers should avoid if they want to create an excellent resource.
Let’s start!
Having No Documentation Style Guide
When users access your documentation, it’s important that they immediately feel like they’ve found a resource they can rely on.
How you present your documentation to users can significantly affect how they perceive it.
Do you want your documentation to project an image of a consistent, reliable, and authoritative information resource that readers can depend on and use as a reference for all their knowledge-based needs?
If you do, don’t make the mistake of not having a documentation style guide.
Here’s how they explain the importance of a style guide at Write the Docs, a global community of technical writers:
In other words, a style guide sets the standards for writing documentation.
It defines the structure, use of language, voice, tone, and other elements that make documentation easy to read, comprehend, and trust.
And the more people contribute to the documentation, the more indispensable a style guide is.
For example, imagine ten developers writing code examples in the documentation.
Without clear instructions on writing and formatting code and code comments, the documentation could become an inconsistent mess of different styles.
That’s why software companies like Red Hat have style guides to avoid those potentially confusing situations for readers.
You can create a style guide on your own, laying the foundations for writing consistent and clear documentation.
On the other hand, that’s a time-consuming process. Therefore, instead of creating a style guide from scratch, you can reference one of the many well-known style guides.
For instance, the Google Developer Documentation Style Guide is a comprehensive resource that provides guidance for every documentation element.
Below, you can see their advice on the grammatical treatment of code elements.
Detailed guidance like that saves time for your developers who write documentation because they have clear instructions available a few clicks away.
There is no need to discuss particular situations with other developers or try to figure out the best way to present information.
Don’t make the mistake of not providing a style guide. Your developers and your readers will appreciate the ability to use one.
Failing to Notice Grammatical Mistakes
No matter how experienced or knowledgeable, every developer sometimes makes mistakes while writing code. That’s a perfectly normal part of their job.
That also applies to writing documentation. Regardless of how skilled at writing, everyone occasionally makes grammatical errors.
Mistakes themselves aren’t the biggest problem in these situations—failing to notice them is.
Just as not noticing a mistake in code would cause software not to work properly, not fixing grammatical mistakes can compromise not only the quality of the documentation but also the reputation of your whole company.
There’s data that indicates how important grammar is to people.
In a recent survey by Tidio, nearly 52% of the respondents expressed a belief that grammar usage reflected a company’s professionalism, while 35% considered grammar important for the company’s credibility.
If we put that together, 87% of respondents think improper grammar usage can make you look unprofessional or take away from your credibility.
Therefore, it’s best not to let grammatical mistakes go unnoticed.
The simplest way to prevent that from happening is to make sure to thoroughly proofread the documentation.
By proofreading, you ensure that mistakes don’t turn the documentation created by hard work and dedication into a resource that will project an unprofessional image.
Julian Tavalin, a marketing expert at Exadel, puts it like this:
The point is that the grammatical mistakes are catchable. And if you don’t want to rely on someone to catch them, you can use software tools.
For instance, most word processors have spell checkers. If you write in Google Docs, you can find it under the “Tools” tab.
If you want a more advanced tool with more features, you can use Grammarly.
Its free version will check for grammatical errors and is available in any browser, which is very convenient.
Let’s see how it works when we add a few paragraphs of text from a DigitalOcean API documentation.
As you can see, Grammarly found one grammatical error, highlighted it, and offered a solution and an explanation of why using that particular word is a mistake.
Whether a tool like Grammarly notices the mistakes or a live person who proofreads the documentation, it is key to detect and fix the mistakes.
Failing to do so can negatively affect how your users perceive your documentation and, by extension, your product and company.
Not Adding Enough Examples
Code examples can play a crucial role in how likely developers will use your documentation.
More specifically, the more code examples you have in your documentation, the happier the developers will be.
Why? Because they don’t want to necessarily read page after page of text, descriptions, and explanations, regardless of how well those are written.
Developers want to see how the code works and try it out for themselves.
This tweet from software engineer Mike Fiedler can give you an indication of how important code examples are to developers.
Code is like a different language, and communicating in code is the most efficient way to show your users how the product works.
So, code is what developers are looking for in the documentation. For example, Twilio, a cloud communication platform, is well known for its documentation brimming with code examples.
You can see below how they organized their documentation to provide code examples in various programming languages and frameworks.
However, they didn’t always have that approach to documentation.
Jarod Reyes, their former manager of various marketing positions, spoke at the SIGNAL conference in London about how they realized the importance of code examples.
Source: Twilio on YouTube
As he said, being developers themselves, the team at Twilio realized that their code samples were their biggest asset.
The users often wouldn’t bother reading the text on the page. Instead, they’d glance at the code examples to see if that was what they were looking for.
Code was giving the developers all the context they needed whether this page had the information they were foraging for.
Twilio also backed their findings with data.
After analyzing multiple metrics, they concluded that the pages with less than four sentences of explanations before a code sample performed twice as well as a page with 11 sentences before a code sample.
Twilio’s example indicates what developers want when they go to a documentation page.
They want to see under the hood of a product—how it works, what it can do, and how they can use it to fulfill their needs.
Without code examples, it’s unlikely that they’ll get what they want.
Forgetting to Maintain the Documentation
Software products are dynamic. They regularly change, update, evolve, get and lose features, and all of that to stay relevant on the market.
The developers are well aware that’s just the nature of software products, and they need to constantly find ways to attract new customers and retain existing ones for a product to be successful.
However, the documentation should also keep up with the product changes to stay relevant and accurate.
The fact that developers are, in general, more technically knowledgeable than average product users doesn’t mean that they can and will tolerate outdated documentation.
On the contrary, up-to-date documentation might be even more vital for developers because it’s one of the resources they use to do their job properly, like this developer below is trying to do.
If you don’t maintain your documentation, that can drive developers away from your product because they don’t have a reliable information resource.
Outdated documentation is something developers using Ubuntu also often deal with.
For example, below, you can see the documentation page about servers.
The problem becomes apparent when you click on the first link on the list that should guide you to documentation about basic networking.
Instead, it guides you to this:
There are more issues with Ubuntu documentation.
Although other links mostly work, some lead to documentation that hasn’t been updated in a long time.
Some pages indicate that on the top when you open them, like the one with documentation about HomeServer.
As you can see, when developers open that documentation page in the hope that they’ll get the information they require, they instead get the outdated document that offers information for an unsupported software version.
That is something you undoubtedly want to avoid when it comes to your documentation if you want to provide helpful resources.
Therefore, ensure that you update your documentation to reflect changes in your product. That’s the only way you can consistently provide useful information.
Neglecting to Include a Search Function
We can’t know everyone’s reasons for accessing your documentation, but we’re willing to bet on one thing—the users don’t want to waste time looking for what they came for.
Whatever information the reader needs, they likely need it as soon as possible.
After all, documentation is here to provide information for solving problems, accessing features, and successfully using the product in general, rather than for leisurely reading.
The speed of finding information is especially important for developers.
They have a lot of responsibilities on their plate daily, and foraging through documentation is not the most productive use of their time.
That’s why you should include a search function in your documentation.
It’s an effective way to find anything in the documentation quickly. For example, Netlify positioned a search bar on the top of their documentation page so you can’t miss it.
Netlify’s search function is particularly useful because it offers options as you type in the search bar.
For example, as you can see below, if you search for “API endpoint reference”, the search function will provide you with several documents that can be helpful.
That way, even if you don’t immediately find the exact document you need, the search function will point you to possible resources, so you don’t have to rummage through categories and subcategories of content.
That latter scenario can happen if you fail to include a search function in your documentation.
For instance, take a look at the Postmark documentation. It’s well-designed, very detailed, and overall, it’s a great information resource.
However, if you look at the screenshot above, something is missing from Postmark’s documentation page—a search bar.
That means the reader needs to scroll through the table of contents, find the category they think will contain the information they need, open documents, read them, etc.
In short, it’s a process that can take much more time than typing a few words in a search bar, and there’s no reason to subject your readers to it.
Failing to Make Documentation Easy to Find
If your users can’t find your documentation, it’s basically like you’ve never even written it.
That might sound harsh, but it’s true. For the users, there’s no difference between the documentation they haven’t found and the documentation that doesn’t exist.
In either case, they can’t use it, and it isn’t helpful to them.
One mistake you can make regarding the visibility of your documentation is not displaying it on the homepage of your company or your product.
According to data by EveryDeveloper, only around half of the top homepages mention developers or documentation anywhere in the site navigation.
Hiding your documentation doesn’t benefit anyone—your users can’t find the necessary information resource, and the time and effort you’ve invested in creating great docs don’t result in deserved traffic.
It’s better to follow the example of Snowplow.
On their homepage, they link to the documentation not once, not twice, but three times.
First, you can find the link in the main navigation at the top of the homepage.
Next, you can visit documentation when you encounter a link around the page’s center, where Snowplow explains how their product works.
And finally, there’s a link to the documentation at the bottom of the homepage if you missed it the first two times.
All in all, the team at Snowplow certainly didn’t make the mistake of hiding their documentation.
However, in addition to making it visible on your website, you should also ensure users can find it via search engines.
For example, many people would rather type in “snowplow developer documentation” into Google than go on their homepage. Simply put, it’s faster and easier.
That’s why you should use a documentation platform like Archbee that allows you to control the SEO meta attributes of each document.
You can control the URL key, title, description, and preview image.
All those elements can make your documents easier to find by ensuring they rank better in search engine results.
Conclusion
Documentation is a vital aspect of software development that shouldn’t be overlooked or neglected.
By avoiding the documentation mistakes we’ve presented in this article, developers can save themselves, their team members, and other users a lot of time and patience.
Instead, avoiding these mistakes will result in a high-quality, comprehensive, and helpful resource that will help create better software products.
