5 tips to write good developer documentation

All developer tools go through five stages: discover, evaluate, learn, build, and scale.

While you are in the discovery stage and moving towards the evaluation phase, this is where you should maximize focus on your docs. As they say, “Documentation is the product.” Your aim should be to have a great developer experience and to reduce the time to hello world (TTHW) to five minutes or less.

When developers discover your tool, you only have a few minutes to get their attention. You need to make sure that your docs provide a good developer experience, have more code, and offer a smooth developer journey.

In this article, I will share the top 5 tips on how to write effective developer documentation that you can follow to write good Stripe-like developer documentation.

Here are some of my favorite developer docs today:

1. Stripe - Every technical writer I know has taken reference from the Stripe docs. It is their simplicity, attention to detail, and structure that make it one of the best developer documentation.

2. Twilio - As somebody who has used Twilio a lot, one of the main reasons why I chose it over other alternatives is because of their quickstarts. Twilio has a great time to hello world (TTHW), which makes developers stick to it.

3. Microsoft - Microsoft docs are extensive and well-structured, showing Microsoft's commitment to developer education. The developer journey, module structure, and sandbox environments make their docs a complete package.

4. AWS - AWS docs are extensive and detailed. They include potential errors and solutions, preventing developers from getting stuck and switching between support forums, which also helps with developer retention.

5. Appwrite - Appwrite treats its documentation as a product. With tutorials and quickstarts in multiple frameworks, it's easy for any developer to get started. They excel in search and versioning, addressing common issues developers face due to version differences and updated methods not well-documented.

Let’s see what made them to the top five developer documentation:

1. Knowing your audience.

The first step to writing good documentation is to know who you are writing it for. There are multiple types of developers depending on experience, tech stack, and more.

Who is your target audience? Who are you writing it for? To know the answers, build developer personas, and talk to the developer community.

Here are some ways to identify your audience:

1. Use social media (ask questions, do polls, gather as much information as you can).

2. If you have a developer community, send out user feedback forms and learn what your developers want.

3. Use community tools that help you follow a developer’s journey on your product, and use that to improve your product and docs.

2. Choosing the right documentation tool.

Developer tools grow fast, and you need to ship your documentation simultaneously. Investing in the right documentation tool is very crucial, as it can build or break the developer experience.

You need to make sure that you choose a tool that:

• Is easy to set up and get started (Documentation in itself is a lengthy process, and you cannot be stuck on getting started using a platform).

• Offers a good developer experience and also gives you all the control to tailor your own experience (like branding, embeddings, and more).

• Allows developers to experiment with your product. Developers want to build, and the best way to get them to use your tool is by providing a playground within your documentation. So, ensure the documentation tool you choose has an option to add a playground.

• Has AI tools that help you fix spelling, grammar, and other details (In this AI era, you shouldn’t have to juggle multiple applications and extensions to fix a semicolon).

• Helps you understand how your documentation is performing and includes a feedback system.

A tool that does everything I just mentioned is Docs by Hashnode - you get all the goodness built within.

3. Writing code samples and API references that are easy to follow.

“Less talk, more code” should be your mantra when writing developer documentation. Every concept needs a code example or real-life implementation. Include API references, quickstarts, examples in various frameworks, and integrations.

If you are not aware, there is a “credit card hell” that most developer tools have. Before a developer gives you their card details, you need to convince them 100% that they need it and that you are actually a developer tool that makes their lives easier. It is your docs that will do the convincing.

Here’s an example of documentation built with Hashnode’s documentation tool that includes an API reference and a playground, making it easy for developers to follow:

4. Having a well-defined structure.

Your documentation should have a structure that is easy for your developer audience to follow. Take an example of the Microsoft docs, despite of being extensive, it is very structured. This helps in onboarding all levels of developers quickly, while also educating them about the product.

To improve developer documentation for beginners, you need to create a developer journey that makes it easy for them to build with your tool. Think of it like learning to write: we start with alphabets, then simple words, sentences, and paragraphs. Your developer documentation would follow a similar structure—basic introduction, installation, and a "hello world" program.

Your product adoption relies on both documentation and support. In fact, your documentation is the main source of truth for support. Having an AI-powered chatbot within your documentation can help developers ask questions and get answers instantly. This prevents them from switching between a community channel and the docs, allowing them to get help directly from the source.

The Requestly docs, powered by Docs by Hashnode, are a great example of how clear navigation and AI-powered search and chat can improve the developer experience with built-in features.

5. Introducing a feedback loop to improve your documentation.

Documentation is a continuous process. You need to keep improving it as new frameworks come up, software architecture evolves, and reading patterns change. The best way to do this is by having a feedback loop. Listen to your users and improve based on their input. This is why having a feedback system and tracking analytics is important.

This is where a product like Hashnode’s documentation tool can help. With a built-in feedback system, you hear directly from users about your documentation's quality and areas for improvement. It also features a dashboard with detailed analytics and smart reports.

Conclusion

Writing developer documentation is challenging, even more so than writing code. You need to balance providing the right amount of information and enough examples while focusing on the developer experience.

Building developer experience in-house can be a very time-consuming process. Instead, you can choose a documentation tool like Docs by Hashnode that handles all of it for you, making it easier for you to focus on the content and the code.

I hope this article has helped you get a good start and understand the key areas that can make your documentation better, especially when writing user-friendly developer guides.