A Manual That Contains Standards For The Design And Writing Of Documents

How To Write Good Software Documentation

A good story is what grabs developers' attention and makes them stay on your website. The story can be anything, but it needs to immediately tell the developers how they will benefit from using your product. A meaningful HW example is an example that brings minimal value regardless of its simplicity. The only goal of any HW app is to show developers how to get started with your product. A journey-based documentation structure mimics the linearly growing complexity of a journey from the first steps to the first easy steps.

Evgeny Kim Hacker Noon profile picture

As tech is growing continuously, more and more companies rely on providing free and paid APIs to grow their business.

However, simply providing an API or a software platform without putting effort into making it attractive is insufficient. Conversion does not happen miraculously. At least, not without marketing.

Marketing a product, especially a software product, is a difficult thing. You need to be always reaching out to developers, building a first-class developer portal, and, of course, offering something valuable and unique. And these are just bare-bone ingredients of success.

One of the crucial elements of a successful developer marketing campaign is documentation. As one of my friends from IT used to say, "No docs, no apps," referring to the fact if your documentation sucks, nobody will even play around with your API.

The Internet is destroying our attention span. We process around 34 gigabytes of information daily. At such a scale, our brains cannot focus on random information for longer than a few seconds.

If this new information doesn't touch us in some personal way, we move forward. This means that one of the crucial steps in making your API or software product successful is to grab a developer's attention instantly.

This post will talk about how documentation can help grab developers' attention and make them stay on your website. Specifically, I will talk about three ways to make your documentation stand out.

You Need to Tell a Story

Everyone loves a good story. A story is what grabs your attention. A good story is what makes you stay. Starting from the landing page of your docs, you must tell a story. The story can be anything, but it needs to immediately tell the developers how they will benefit from using your product.

Take a look at the landing page of the Mailchimp portal, which is a good example of how to tell a story from the very first sentence making developers want to stay on your site.

The story is simple: using Mailchimp, you can manage your site's audience, running campaigns, and much more. If I were looking for a mail list management solution, I would definitely give Mailchimp a try just after a few seconds spent on the landing page.

You don't need to tell a story in just a few sentences, of course. For example, the Keras portal tells its story on the entire web page, starting rather on high-level enumerating benefits of using its API down to low-level advantages such as ease of deployment, high speed of implementation, and state-of-the-art research behind its machine learning API.

When telling a story, make sure you don't overhype your product. Focus rather both on the result and actions available to developers to achieve their goal.

Always Have a "Hello, world" Example

When talking about software documentation, it is hard to understate the importance of a demonstrable and clear "Hello, world" (HW) example. Ideally, an HW app is the first thing your users should do after obtaining access to your API or software.

It doesn't need to be complex, nor does it have to be overly simplified. And it doesn't even need to print "Hello, world!" in the end.

The only goal of any HW app is to show developers how to get started with your product.

How developers get started with your product depends heavily on the product's purpose. Therefore, there is no single formula for now to write an HW app. However, the best practice would be to identify the simplest usage for your product that is both meaningful and demonstrative.

A meaningful HW example is an example that brings minimal value regardless of its simplicity. A demonstrative HW shows how to achieve this value with a minimal set of steps. Keep this in mind when creating an HW example for your software.

Structure Your Docs Based on a Journey

When you offer developers an API or software, you invite them for a journey. This journey starts from the moment they land at your portal and ends with celebrating their success, which is a working app ready for deployment.

If you care about your developers, your job is to make their interaction with the product you offer as smooth as possible, removing unnecessary friction from the developer journey. One of the best ways to combat API friction is by adopting a journey-based documentation structure.

A journey-based structure mimics the linearly growing complexity of a journey, from the first easy steps to the first challenges to the climax to celebration of success after the journey is over.

Very few people will set out on a journey that has no clear structure or destination. You need to make sure that you outline the entire journey from the very beginning. If possible, do it with the "Hello, world" example, boiling it down to the essential ingredients but incorporating all the developers' steps needed when building their solution. If putting everything to the "Hello, world" is not possible, then have a separate chapter that introduces the entire developer journey, explaining all the steps developers need to take to deploy their application.

Every product has a different type of journey. As with the "Hello, world" example, there is no right way to structure it. Just make sure that developers understand and foresee the effort required to implement your API or adopt your software.

In this post, I presented three ways to improve your API or software documentation. The three ways are:

You need to tell a story
Always have a "Hello, world" example
Structure your docs based on a developer journey

I hope this information will help you in improving your documentation.

Previously published at https://evgenykim.com/2020/11/29/3-ways-to-make-your-software-documentation-even-better/