Developer documentation forms the experience of every developer working with a particular digital product.
The documentation gives developers the necessary information to understand and utilize the software efficiently.
However, not all developer documentation is created equal.
To truly be an effective and informative resource to its target readership, good developer documentation needs to have certain attributes.
In this article, we’ll explain what those are, and help you understand why they’re necessary.
Let’s start with the first one!
Discoverability
You and your team have spent weeks, if not months, creating outstanding developer documentation, but the developers don’t use it as much as you expected.
How can that happen? Well, it might be that your developer documentation is just hard to find.
First of all, you should ensure they can easily find documentation when they visit your product’s website.
A link at the top or the bottom of the homepage is more than enough. Below, you can see how Slack makes it clear how to get to the developer docs.
And although it’s important to make links to resources for developers visible, the truth is that most of your users won’t get to documentation through your website.
Most people today find what they need on the internet with the help of search engines. It’s much faster to type a few words in the search bar than to go to the website and comb through it.
Mark Baker, the author of the influential book Every Page is Page One, wrote about how websites don’t matter that much because search engines give more weight to individual pages.
What does that mean for the discoverability of your developer documentation?
It means that search engine optimization (SEO) is of utmost importance. The search engines will return results leading to specific pages that answer the search query.
Let’s go back to the example of Slack.
If a developer wants to find the documentation about Slack Events API by googling it, it’s vital for Slack that their documentation shows up at the top of the search results.
As you can see, Google gives the curious developer several links related to the Slack Events API, which means that someone at Slack has done a great job with SEO optimization.
You can propel your developer documentation to the top of the search engine results using a documentation tool like Archbee, which has SEO meta controls.
You can tweak the URL key, title, description, and preview image to improve the SEO performance of your document.
They all have their role in SEO performance. For example, by changing the title, you can optimize it for SEO keywords that will help rank your documentation page.
What is essential in the end is that developers are able to find the resources they need with ease. Otherwise, all of the time and effort are in vain.
Usability
Another important attribute of good developer documentation is its usability. Let’s examine what it means to have usable documentation.
For starters, it goes without saying that you want to provide as much information as possible in your documentation.
The docs you provide are a source of information for developers, so if they can’t find what they need, what’s the point of the resource itself?
However, that’s where we arrive at the importance of usability. The amount of information you provide in the documentation shouldn’t overwhelm or intimidate the readers.
While it’s vital that the information is there, the users should still be able to find their way around all that content. Otherwise, they’ll be hesitant to use the documentation.
Luckily, if you include a few crucial elements in your documentation, its usability will skyrocket.
To begin with, the important thing to remember is that your developer documentation is not a book, and users won’t approach it like that.
As Josh Fechter, a technical writer and founder of several tech companies, points out, users won’t read your documentation from cover to cover.
They will be seeking specific information, so you should structure your documentation accordingly.
For example, let’s look at GitHub’s documentation for REST APIs.
On the left-hand side, there is a list of all of the subcategories and pages inside the REST API documentation. Below, you can see only a partial list.
Also, on the right-hand side, every page has a table of contents that shows the reader what is in the document.
The purpose of all that is to make navigation easier, both at the level of the documentation as a whole, as well as inside specific documents.
The more content you have in the developer documentation, the more useful navigational elements like those are.
What is also helpful is a functional search bar. In GitHub’s documentation, the search bar is in the top right corner and always accessible.
If a developer wants to find documentation about, for instance, REST API deployments, the search bar will deliver.
Structuring your documentation and providing ways to navigate it is crucial for the usability of developer documentation.
Developers often need information quickly, and they will be grateful to be able to access it thanks to your careful organization and planning.
Quality
If you ask a hundred developers what makes high-quality developer documentation, you might get a hundred different answers.
However, it’s very likely that certain elements will regularly pop up in those answers.
Elements like accuracy, completeness, readability, cohesion, and clarity are reliable signs of high-quality developer documentation that can be helpful to developers regardless of their experience and expertise.
Simply put, developers use documentation to get informed, learn, and do their job better. If the documentation helps them to be better at their job, that’s a sign of a stellar resource.
On the other hand, if the documentation causes them to make bad decisions and compromises their results, its quality isn’t good.
Let’s focus on some of the elements of high-quality documents mentioned earlier and start with accuracy.
It goes without saying that documentation shouldn’t have grammatical errors. You can ensure they don’t end up in the text by running it through a tool like Grammarly.
It’s a powerful editor that points out grammatical errors and incorrect punctuation, while also offering suggestions for sentence structure, proposing more engaging terms to use, highlighting clarity issues, etc.
In short, it analyzes your text and suggests improvements to make it more accurate and refine your writing style.
And while we’re talking about writing style, clarity, and easy comprehension, there’s another tool worth checking out—Hemingway Editor.
Its specific purpose is to make your writing clear and easy to read.
For example, let’s look at one part of Vimeo’s developer documentation about registering your app.
If we run it through Hemingway Editor, we can see the analysis and if the tool offers any suggestions for improvement.
As you can see, according to Hemingway Editor, Vimeo’s documentation has a grade 2 readability, which is very good on Hemingway’s scale.
The only issues are two uses of the adverb “maybe”, which we could also attribute to the laid-back writing style of Vimeo’s docs.
Overall, the elements of quality we’ve mentioned earlier, like clarity, conciseness, and readability, are all at the highest level in this example.
Providing accurate, easy-to-understand, clear, and well-written developer documentation is a sign that you invested in creating a quality resource.
Helping yourself with tools like those we’ve mentioned can only improve your docs.
Interactivity
Skillful writing goes only so far when it comes to developer documentation. A truly great resource for developers should also be interactive.
We don’t mean to imply that the quality of writing isn’t that important for developers. After all, we’ve dedicated a whole previous section specifically to the importance of writing.
However, developers are practical, and they love to learn by doing.
By interacting with the code, they can more easily understand the complex nature of a software product than by only reading about it.
That’s why it’s great that you can show developers the code inside the documentation itself, and they’ll surely appreciate it.
For instance, Gunnar Morling, a seasoned software engineer, was delighted when JavaDoc introduced the feature of pulling in example code.
Creators of developer documentation are increasingly aware of the convenience of including actual code in the docs.
Also, they don’t just include code examples that illustrate their explanations and tutorials. They go a step further and make the code interactive.
For example, Clearbit’s developer documentation has code examples in several programming languages on the right-hand side of the webpage.
However, users can also try out examples in an API platform Postman with the click of a button.
There are more ways to make documentation interactive with code examples.
Let’s take a look at the documentation for Vue.js, a JavaScript framework.
Its documentation is generous with code examples, but that’s not all. The users also have the option to try out the code in the Playground.
The Playground is where developers can interact with the code, experiment, and test what it can do.
It’s a great way to play around with the code without any risks or stakes.
Giving developers an opportunity to interact with your documentation can raise it to another level.
Devs want to read well-written paragraphs about APIs, endpoints, HTTP request methods, and everything else that good documentation includes.
However, an option to see the code at work and interact with it is much more effective.
Repetition
In the field of software development, there’s a well-known mantra that you’re undoubtedly well-acquainted with—don’t repeat yourself.
Abbreviated as DRY, this principle aims to reduce code duplication and repetition of patterns to avoid redundancy.
Here’s how David Thomas and Andrew Hunt explain DRY inThe Pragmatic Programmer,a book that popularized that principle.
DRY is about the duplication of knowledge, of intent. It’s about expressing the same thing in two different places, possibly in two totally different ways.
And although they argue that the DRY principle extends beyond code to databases, tests, and even documentation, moderate repetition can be beneficial if your goal is to educate developers through good documentation.
Why? Well, as we’ve mentioned earlier, developers tend to read the documentation as needed and look for specific information instead of reading it from the first to the last page.
That means they can find a piece of information they need easier if it’s in multiple places in the documentation.
This doesn’t mean you should copy and paste the same paragraph a few times across the documentation and call it a day.
Repetition comes in various forms that are more efficient than that.
For instance, Atlassian often includes summaries at the end of the documentation pages.
Their summaries provide a quick overview of the content the users have read and often include links that are already dispersed throughout the document.
That way, developers can have the most important takeaways and the links to other resources in one place.
Atlassian also created another helpful form of repeating content—a Git cheat sheet.
As they explain, it saves developers time when they get stuck and can’t remember a command.
Of course, all the information in the cheat sheet is also spread across Atlassian’s developer documentation.
Regardless of that, repeating it in one handy resource is a violation of the DRY principle most developers would be glad to see.
Being Up-To-Date
All the attributes we’ve mentioned so far are essential for top-notch developer documentation.
However, even they can’t save outdated documentation from being useless.
Your documentation needs to reflect the changes your product goes through and the state that it’s in.
As Mike Pope, an experienced technical writer and editor, puts it, the documentation makes those changes visible to users.
In other words, every update, every added or removed feature, and every change to your software product should be documented.
If it’s not, from the user’s point of view, it didn’t happen. If they use documentation as a source of information, all the information should be in it.
However, updating documentation can be challenging, especially if the developers are assigned to do it.
As Steve Konves, a software engineer and blogger, explains, there isn’t always time and motivation for updating the documentation.
When time or motivation is limited, if you have the choice between updating either the code or the docs, it’s usually just the code that gets any attention.
The solution can be to update the documentation as soon as the software changes occur.
The longer you postpone updating the documentation, the higher the chance it will become obsolete.
Also, you should have a way to notify your users of both the changes in the product and in the documentation.
For example, Intercom has a changelog where they document changes in their API.
As you can see, it’s a simple table with information about the version, its release date, and a link to the API reference.
If a user clicks on the name of one of the versions, the link leads them to a brief explanation about what’s new in it.
And if developers are interested in more details about a particular change, they can follow the link to the document that explains it.
For instance, if you click on the link about a new webhook topic you can see in the screenshot above, it takes you to the page where you can find that new webhook, along with other information about webhooks in general.
That way, Intercom keeps their docs up to date. Every change is announced, briefly explained, and documented.
It’s a system that requires good organization and dedication but results in relevant documentation.
Providing outdated documentation to developers will result in wasting their time, which is something that benefits no one.
Conclusion
To sum up, it’s highly unlikely that you’ll create remarkable developer documentation on accident.
To achieve that goal, you should know what makes good developer documentation good.
Luckily, if you made it to this point in the article, you now know what attributes you should pay attention to when creating resources for developers.
Now the only thing left is to combine them into documentation that will give developers everything they need.
