Best and Worst Practices in Technical Documentation

Best and Worst Practices in Technical Documentation

Recently, I have been perusing documentation pages from various web2 and web3 companies. While reading these pages, I have observed both good and bad practices. Instead of creating a tutorial or guide, I have decided to share my observations in this article without naming any specific companies.

Good Practices

These are the reasons why I felt comfortable using these Docs. I would recommend them to other developers, and they made my tasks easier to complete quickly.

Show not tell

To make it easier for developers to understand and implement the information in the documentation, demonstrate use cases and visual aids to illustrate concepts instead of just explaining them.

Keep in mind that when users get to your Docs page, they want to know as quickly as possible if your solution is suitable for their needs. It's essential to show the core benefits of your protocol or product and remember that the Docs landing page presents your company.

Developers need to know if your API or solution will solve their problems as soon as they arrive on your page, so make it clear and easy to understand.

Quick Starters

These small guides are the most important pieces of your documentation. I recommend backing each of them with a GitHub repository. Some developers refer to this guide as the "Hello World" tutorial, as it is often the first tutorial developers create.

It's great to experience the power and satisfaction of passing the tests on your screen. After completing the basic tutorial, you can create a simple task tutorial. Then, you can move on to show how your protocol can be used. In the case of web3, you will most probably deploy to testnet as a stage environment instead of a production environment.

Plant the seed

Developers are often creative, but sometimes they need a gentle push to start. Providing examples of highly-used cases for the protocol can be helpful. For instance, minting an NFT featuring a favourite animal such as a dog or a kitten.

Inspiring your users can help steer them in the right direction and ignite their enthusiasm for the project.

We’re all Slytherins

It's a joke among Python enthusiasts😂, but it also applies to any language fanatic who looks through your docs for their preferred language. If you don't provide that content in a language-specific style, they might skip your product altogether. To make it easier for developers to onboard, most web3 protocols provide code in Javascript, Python, and Go programming languages.

Hot Copy-Paste

This feature is hugely underrated when going through the Docs searching for a specific piece of code you need to test and inject into your application like the “error message” you get when you’re not connected to the right chain when attempting to connect your wallet.

Another example is when you create an API key, then simply click that copy button in the upper right corner and you’re good to go😎.

Latest Updates

It is important to keep your documentation up-to-date with product updates. The OpenAPI initiative provides a standard for creating and maintaining API references, which is one of the documentation structure styles.

OpenAPI can generate machine-readable references that stay updated with any changes or updates to APIs. Many companies use this tool to keep their API reference users informed about any updates to their APIs.

Interactive Playground

What's better than just showing developers what's possible is letting them experience it firsthand within the documentation. The Graph Playground is a great example of this. While learning and going through the documentation, you can copy and paste the code to experiment with it right in the Playground.

Sharing is Caring

If your audience consists of developers, consider sharing solutions to specific problems that your product solves as blog posts. This can be an effective way to educate and inspire more developers to use your protocol.

Personally, before even looking at the documentation page, I search for blog posts related to the protocol in Hashnode and Medium. These articles can be technical and sometimes cover advanced cases, which can save a lot of time.

This will help improve the experience of your end-users and increase their success rate. For example, Ankr provides a comprehensive blog on Hashnode to assist developers in their search for inspiration.

Developers Feedback

There are several ways to engage with your community on this point. Here are a few examples:

  • Use a "thumbs up" or "thumbs down" system or you can provide a rating scale with at least three options (such as🙂😑😞).

  • For more detailed feedback, conduct user interviews or send out surveys to collect feedback.

Bad Practices

Unfortunately, some great protocols still fall into the trap of using practices opposite to those mentioned above. This results in a bad or annoying experience, causing a big part of their developer community to leave.

Missing Documentation

The absence of documentation or providing broken links to the documentation can be disastrous, especially for APIs. For example, providing documentation only upon request🤯🤯 can lead to frustration and confusion. Similarly, inaccurate or outdated documentation can also be very frustrating for developers.

PDFs

Asking developers to download documentation in the form of a PDF can make their lives harder, as they won't be able to easily copy and paste code snippets and share deep links with others.

It’s not only about PDF format but also any file format that developers are asked to download.

The Lack of Pictures

A lack of opinions and visual aids can make your audience lose interest, especially if there are long paragraphs or a multitude of written steps to follow. It is not an easy task.

Developers are often in a hurry and need quick answers, so they have to search through lengthy documentation pages. Many of us have faced this issue with the knowledge base of large Web 2.0 companies.

Alice & Bob

These variables are commonly used in examples because they represent variables A and B, which makes them easier to remember and understand. This is considered a good naming convention. Using poor names in your documentation titles can be misleading to end-users or developers who come to check your content.

Videos & Actions

Providing only video format for documentation is a bad practice. Users may forget which button to click or may become bored watching a long video without search or copy-paste features.

Additionally, using a picture filled with all the actions or buttons to be clicked written on the screen can be hugely annoying.

Ignoring Something

While following a step-by-step guide on your documentation page, developers suddenly couldn't follow the instructions. Skipping a step can be irritating, especially if it's unclear where to find what has been created after the last step.

This happened to me when I used wsl for the first time. I couldn't locate the directory and it took me a long time to figure out how to access it.

No Feedback

Even if you don't want to include your company's voice or opinions in your documentation, it's still important to gather feedback from developers. Almost every high-quality documentation page I've seen includes this feature.

Conclusion

In addition to the above-mentioned practices, developers often appreciate having documentation available in their preferred programming language. Providing content in a language-specific style can help developers to easily onboard to your protocol or product.

Another important aspect of good documentation is including visual aids and examples to make the content easier to understand. A lack of illustrations and visual aids can make your audience lose interest, especially if there are long paragraphs or a multitude of written steps to follow.

Furthermore, providing a search function within the documentation can help developers quickly find the information they need. Developers are often in a hurry and need quick answers, so they don't have time to search through lengthy documentation pages.

Lastly, if your audience consists of developers, consider sharing solutions to specific problems that your product solves as blog posts. This can be an effective way to educate and inspire more developers to use your protocol. These articles can be technical and sometimes cover advanced cases, which can save a lot of time.

Overall, creating good documentation is a crucial aspect of a successful product or protocol. By providing user-friendly documentation in the preferred programming language, including visual aids and examples, and making it easily searchable, developers will be more likely to use and recommend your product or protocol.