5 Tips For Writing Technical Documentation That Developers Love

#writing #beginners

After I finished writing a blog post on Dev.to, I decided to schedule it to be published the next day. I received the message, "This URL is public but secret, so share at your own discretion." This confused me, so I thought, “Why not check the documentation?” I went to the site’s Editor Guide and found that there was no information about this rule, leaving me with no choice but to sit, wait, and hope for the best.

This is what developers tend to face when referencing unclear documentation when they need to troubleshoot their tools. 48% of Google engineers in a case study revealed that poor documentation negatively impacts their productivity, so it is crucial to have documentation that developers can easily comprehend. Feeling unsure of how to get started? No worries, this article will focus on 5 tips for writing technical documentation that developers love.

Tip #1: Make it Accessible

According to a report done by Click-Away Pound, 71% of users with disabilities will exit a website if it’s not accessible. In other words, developers will struggle to troubleshoot technical errors in your product if your documentation is not presented so that all developers can use it. While we’re assuming that you’ve taken care of basic best-practice accessibility while writing technical documentation, like placing your headings in hierarchical order (e.g., h1-h6) and adding alt text to images, there are other ways you can make your documentation more accessible.

When describing people in your product’s tutorial(s) or pages that describe its feature, it’s best to avoid pronouns like “him/he” and ‘she/her” or terms like “woman” or “man” and instead use terms like “they/them” or “the user.” It’ll help developers of all genders feel welcome. Consider this block of code from OpenSauced’s explainer page for their Insights feature:

### How to Share Insights Page

There are two methods to share your Insights Page:

#### Method 1: Using the Share Button 

This method gives view-only access to your Insights Page.

1. Click the "Insights" tab at the top bar.
2. Click the page that you want to share.
3. On the top right, click the "Share" button to copy the Insights Page URL to the clipboard.
4. Share the URL with your team members.

Save this code

In addition to having headings in hierarchical order, the tutorial also uses gender-neutral language like “you,” which ensures that developers and open-source project maintainers of all backgrounds will feel spoken to. Now, accessibility is just one of the many tips for writing technical documentation. Let’s look at another one.

Tip #2: Balance Technical and Plain Language

When it comes to effective technical documentation writing, most technical writers recommend using plain language and avoiding using as much technical language as possible. While that does make your product’s content more digestible, it is best to implement technical language since the audience you’re writing for is technical. The trick is to describe these terms in a way that developers will understand. Let’s look at an excerpt of this tutorial from the website of the open-source project BioDrop and see how this method is used:

8. Make the changes you require

Changes could include:

- updating your Bio
- adding a new section (see examples below)

| Sections                    | Json object  | Description                                                                                          |
| :-------------------------- | :----------- | :--------------------------------------------------------------------------------------------------- |
| social shortcuts            | socials      | These are the icons at the top of your Profile                                                       |
| tags                        | tags         | These are search keywords for people to discover your Profile (for example `DevRel` or `Javascript`) |
| milestones                  | milestones   | Milestones you wish to highlight (for example "First day on GitHub")                                 |
| testimonials                | testimonials | Include testimonials from other people in the community                                              |
| Virtual or in person events | events       | Show which events you are attending                                                                  |

Save this code

The above code snippet contains a chart that describes specific parts of the JSON file, what each part means in plain language, and provides brief examples of titles. This makes it easier for developers who are familiar with JSON and people who are new to the language to create or update their BioDrop profile. Speaking of examples, I have a tip on how you can make your technical writing and documentation more relatable to developers. Let’s check it out!

Tip #3: Implement Real-life Examples

In college, an English professor would ask me and other students the following question when reviewing our essays, “Where are the examples?” Developers ask the same question when reading your documentation. To write good technical writing documents, include examples that developers can see themselves implementing in their work. How can this be done? By adding examples from your product’s codebase! 🙂 Let’s look at this code snippet from my contribution to GitHub’s documentation:

![Screenshot of a pull request. On the right bottom side, a blue, enabled checkbox, labeled "Allow edits and access to secrets by maintainers", is highlighted with an orange outline.](/assets/images/help/pull_requests/allow-edits-and-access-by-maintainers.png)

Save this code

The above code snippet has a hyperlink to a screenshot that focuses on the feature that permits maintainers to edit pull requests that open-source contributors send to their repositories. To do this, I took a picture of this feature on one of the projects that I co-maintain with my other colleagues and saved the code snippet using Pieces for Developers so that I can reference it in the future. Now, examples are just one way to make developers fall in love with your technical documentation writing. Let’s look at another one.

Tip #4: Add Context to Your Real-life Examples

Remember how I previously mentioned that my college English professors would ask me to show examples in my essays? Well, they would also ask us to explain their significance. This is also applicable when using multimedia in your product’s documentation. While providing examples is helpful, adding explanations is paramount. As Tsavo Knott states in The Art of Writing Documentation and Other Technical Content, “Providing essential context will empower the audience to take a more reasonable approach to solving the project the author is writing documentation about.” Let’s see this in action in my contribution to the Codecademy Docs:

git
git mergetool

Conflicting section:

<<<<<<< HEAD

Creating a Tutorial

We highly recommend using Markdown to create your tutorial for our audio editor.

If you need help, check out our templates.

UPDATING-THE-DOCS


- `<<<<<<< HEAD`: where the developer's changes appear.
- `====`: Divides the developer's changes from the changes in the other branch, followed by `>>>>>>> UPDATING-THE-STYLE-GUIDE`

To complete this command, the developer removes the conflict markers `<<<<<<<`, `=======`, `>>>>>>>`, and pushes the changes to the `updating-the-style-guide` branch with the following commit message:

git
git commit -m "docs: update information about tutorials"

Save this code

In the code snippet above, there are steps on how the git merge tool command is used to solve the merge conflict I mentioned. In my experience, it is best to be as detailed as possible when writing about your examples, so that developers can fully understand how to apply the code or tool in their work. Now if this is something you struggle with, one of the tips for writing technical documentation that I highly recommend is using Pieces for Developers’ copilot chat feature.

You can upload the snippets you’ve saved and you have the option to write your questions as well as ask recommended questions, which can help you quickly think of ways to describe your examples. It’s like having that one friend who knows what you’re thinking before you speak. Now, before you go and start writing, there’s just one more way to make writing technical documentation loveable.

Tip #5: Don’t Rely Too Much on Current Tech Trends

Let’s be honest, it’s tempting to implement popular AI tools like ChatGPT, Gemini (formerly known as Google Bard), and other trends to create your documentation. However, it is best to use your voice and experience because in general, developers tend to be more receptive to documentation that is written by someone knowledgeable and provides simple explanations for complex concepts.

For example, when I was writing about Daily.dev’s video feature for their documentation site, I almost used ChatGPT to give me some ideas, but I then remembered that I use it all the time, so I asked myself the following questions:

How can this feature enhance my experience?
What makes this feature different from other sites like YouTube?

After doing some thinking, I came up with the following content:

# Videos

 Tired of reading blogs or articles to get information about the latest trends? Weep no more fellow techies! :) You can now watch [Ben Holmes](https://app.daily.dev/sources/bholmes), [Fireship](https://app.daily.dev/sources/fireship), and your other favorite tech YouTubers on daily.dev!

 <!-- add Francesco's screenshot here -->

## Help Us Grow Our List!

Feeling like our list is missing some people? Write your suggestions in the [comment section of our release post](https://app.daily.dev/posts/7yqkWkdLc)

Save this code

I wrote about how Daily.dev’s video feature makes it easier for developers to watch their favorite tech YouTubers as well as encourages them to add their recommendations to the comment section of their daily.dev’s release post. If you’d like to use AI to help you write high quality content, without sacrificing the personality of your writing, check out our blog post on the role of AI in technical writing.

Now It’s Your Turn

Whether it is an explainer page or a tutorial, accessibility, balanced language, real-world examples, clear explanations, and your voice are the key factors in writing technical documentation that aids developers in their work. If you’re looking for a place to put this into practice, check out Pieces for Developer’s documentation repository on GitHub. Now, go forth and write excellent technical documentation!