5 Tips For Writing Technical Documentation That Developers Love

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:

- `<<<<<<< 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:

# 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)