Developer documentation contains all the information software developers need to create outstanding products.
As such, that type of documentation is vital—there’s no other way around it. Without outstanding developer documentation, there can be no great software products, either.
That’s why, in this article, we’ll present you with valuable practices you can use to improve your developer documentation and create a top-notch resource.
Let’s get to it!
Be Concise When Writing
Like any other kind of technical documentation, developer documentation has a clear purpose.
That purpose is to provide the developers with the instructions and information they need to build the software and develop the product.
Therefore, developers come to the documentation expecting precise and clear answers to their questions.
Because of this, the developer documentation you create should deliver the information straightforwardly.
Overly complicated sentences, long paragraphs, and flashy language can only impair clarity.
On the other hand, as Jon Beller, an experienced software engineer, advises, you should strive for conciseness.
Concise writing doesn’t necessarily mean having a small word count, although that can be a part of it.
You can also achieve conciseness by using precise wording, short sentences, and small paragraphs in your documentation.
In other words, no matter how much information you need to convey, there’s always a way to present it in a precise and concise manner.
For example, take a look at the excerpt from Docker’s developer documentation below.
It explains a complex container process in one sentence and uses a bulleted list to further clarify the information presented.
Using lists like that is just one of the practices helpful for producing concise writing.
Another one is using a glossary of terms in your developer documentation.
Why? Because if you have a glossary, you don’t need to explain or define every technical term you introduce to readers within the body of the text itself.
Instead, you can link to the glossary when needed and save space in the document.
For instance, Microsoft uses that practice in their developer documentation for Microsoft Teams.
Having an extensive glossary like Microsoft’s can undoubtedly help you with your word count, but also make documentation more succinct on the sentence and paragraph levels.
In summation, the words of Maybell Obadoni, technical writer and software engineer, can tell you what to aim for when writing developer documentation:
A good document isn’t one with complex grammatical constructions, but rather, one that is relatable, straightforward, and clear.
By following that advice, you can certainly improve your developer documentation.
Avoid Using Technical Jargon
It goes without saying that you want your developer documentation to be understandable to all developers, from beginners to experts.
You never know who might come across your documentation, so it’s best to write it in a way that caters to a wide audience.
Avoiding technical jargon in your writing is a surefire way to accomplish that.
In other words, using niche terminology, abbreviations, and complex terms can make your documentation difficult to understand, leading to frustration on the part of the reader.
As Mason Egger, developer advocate, programmer, and speaker, explained in his talk at PyCon US, you should simplify your writing to improve your documentation.
Simply put, technical jargon makes communicating information needlessly complicated.
There’s almost always a way to present the same information using plain language.
However, if technical terms are unavoidable in some parts of the documentation, it’s best to use standard industry terminology that developers are likely to be familiar with.
What does it look like when writers get carried away with technical jargon? Kin Lane shared a story about encountering an unfamiliar acronym in one API resource about managing DEGs.
What is a DEG, you might ask? That’s the same question that was on Lane’s mind while reading the resource.
You could add, update, delete and get DEGs. You can also pull analytics, history, and other elements of a DEG. I spent about 10-15 minutes looking around their developer portal, documentation, and even Googling, but never could figure out what a DEG was.
On the other hand, there are examples of excellent API documentation that use simple language and are accessible to a wide range of readers.
One of those examples is Amplitude’s documentation. Take a look at an excerpt from it below.
It explains event properties in one sentence and follows that definition with an example.
After that, the developer can read the code snippet and observe the chart for further clarification. There’s no complex technical jargon, slang, or rarely-used terms.
If you want to improve your developer documentation, that’s the kind of writing you should practice.
Be Sure to Include Code Snippets
As we’ve mentioned earlier, one of the ways you can improve your developer documentation is to make sure it conveys information with precision and clarity.
When it comes to the documentation aimed at developers specifically, that information includes how your product works.
In other words, developers want to peek under the hood of your product and see what drives it. And what drives it is code.
So, instead of describing it in the documentation, why not show them the code directly?
That’s what code snippets are for. They are small sections of code that serve as a sample that shows the developer what your product can do and how it does it.
And developers love code samples. They’re immersed in writing, reading, and fixing code for hours on end, so they feel at home with it.
As Jarod Reyes explained in his talk about Twilio’s documentation, developers love reading code more than reading sentences.
Any time that there was a lot of prose on a page and there wasn't a lot of code, that page didn’t perform well.
Luckily, there are multiple ways in which you can include code snippets in your developer documentation.
For example, below, you can see how DigitalOcean does it.
They simply insert the code snippet in the text, separating it from the text with a gray box and differently colored font.
There are other methods, too. For example, some developer documentation, like Clearbit’s, shows code snippets alongside the text and includes tabs for different programming languages.
That way, a developer can switch between tabs and see how the code works in Shell, Ruby, Node, Python, or whatever other languages and frameworks are included.
As you can see, code snippets can be handy for developers.
After all, most developers think in code, and it’s like a second language to them, so showing it to them directly is a great way to elevate the quality of your documentation.
Add Media to Your Documentation
Developer documentation usually consists of text and code snippets. Those are fundamentals of your developer documentation, but if you want to build upon them, you can add visuals.
Media like screenshots, GIFs, and videos can make your developer documentation stand out from the rest.
It’s not easy to see why. People are attracted to visuals—they make documentation more engaging and even more helpful.
How? Well, visuals can help readers remember information better. According to author John Medina, if you hear a piece of information, you’ll remember 10% of it three days later.
On the other hand, if that piece of information is paired with a visual, you’ll remember 65% of it in the same time frame.
So, how can you pair text and media in the developer documentation?
One of the simplest and most effective ways is to use screenshots.
Screenshots allow you to illustrate anything you’re describing in the text. You can use them to show complex procedures with a few images instead of elaborate written descriptions.
For example, Render uses screenshots in their developer documentation along with the text, just as Medina advises.
As you can see in the example above, they describe to a developer where they can find the Deploy Hook URL and complement that with a screenshot.
That way, even if the written explanations are too abstract or complex, an image can show the readers if they’re on the right track.
Below, you can see another example of Render writers using screenshots in the documentation.
This time, they use them to illustrate a step-by-step guide on configuring Cloudflare DNS.
As you can see, there is some text, but the screenshots are doing most of the heavy lifting.
The outcome is that the guide is understandable and straightforward, even for developers unfamiliar with the software interface.
If you want to improve developer documentation, adding media is an excellent way to do so.
As John Collins, consultant and advisor to tech companies, points out, neglecting visuals would be a mistake.
Visuals catch the eye and make information easier to understand and remember, so it’s important to leverage them in your documentation.
Choose a Good Documentation Tool
A modern documentation tool facilitates creating well-written, detailed and helpful documentation for developers, and makes using that documentation a smooth experience.
How? For instance, a good documentation tool allows you to keep every piece of information in one place.
It serves as a repository for everything developers should know, making accessing the information easier for them and for you as the creator.
The developers know where to find what they need, and you can keep your documentation updated and under control at all times.
For example, keeping documentation up to date is something that most developers consider particularly important.
However, according to the GitHub Open Source Survey, 93% of developers have stated that incomplete or outdated documentation is a pervasive problem.
It’s easy to see why. If the documentation lacks relevance, it’s virtually useless.
But with a top-notch documentation tool, you can create documentation, organize it, and store it in one place, which makes updating it a breeze.
Also, it allows you to improve it by including all of the elements we’ve discussed so far, like media and code snippets.
If you’re looking for a tool with all those features and more, try Archbee.
Archbee is a documentation tool that is tailored for creating high-quality documentation.
For instance, you can enrich it with code samples, as Klevu did in their documentation created with Archbee.
You can also add media like videos, GIFs, images, or annotated screenshots.
Below, you can see another example of that from Klevu’s documents.
The point is that a good documentation tool enables you to create accessible and helpful documentation for developers that can be easily maintained and available in one place.
In other words, it allows you to make good documentation even better.
Get Feedback on Your Documentation
One of the simplest ways to improve your documentation is to get feedback from the people you made it for—the developers.
You can create documentation with all the best intentions, and it might seem flawless to you, but you don’t necessarily have the same point of view as readers do.
For instance, you need to have a certain level of expertise about the subject matter in order to write about it.
However, not every reader is necessarily on that level, and what can seem simple to you might be incomprehensible to some of your readers.
Therefore, the feedback can tell you which areas of documentation are lacking, where you can make changes and improvements, or simply adjust documentation to your readers’ needs.
You can gather that feedback in many ways. One of the simplest is to ask for it directly in the documentation.
For example, that’s how Twilio does it. They have a star rating system on every page of their developer documentation.
A rating system can tell you which parts of your documentation need more work, so it’s a good starting point.
However, that method can’t tell you why readers rated certain parts of the documentation better or worse than others.
That’s why surveys are useful. For instance, SIOS created a survey with SurveyMonkey software to gather feedback about their technical documentation.
Above, you can see one of the questions from it asking users to rate various documentation elements on the scale.
They’ve also included other types of questions, including open-ended ones. Answers to those can provide concrete and helpful suggestions for improving your documentation.
To summarize, in order to take your documentation to the next level, you need to know what to improve in it in the first place.
Feedback from people who use it regularly can be invaluable for accomplishing that goal.
Conclusion
Developer documentation takes time to get right.
If you’re creating it, you’ll likely spend many hours tweaking and perfecting it so that you can provide developers with valuable and helpful knowledge resources.
Luckily, if you are concise when writing, avoid technical jargon, include code snippets, add media, have a great documentation tool, and look for feedback on your documentation, you’re on the right track.
See how Archbee can enhance your technical documentation processes with our free 14-day trial.
