How programmers write good technical documentation how to write high-quality API documentation work

Writing technical documentation is one of the most daunting tasks for many developers. It itself is a time-consuming and laborious job to do well. But most of the time, people are always trying to take shortcuts, and the results are often very regrettable, because quality technical documentation is an important factor in determining whether your project is a concern. This is true for both open source and developer-oriented products.

In fact, what I want to say is that for developers, the most important part of their user experience is not the homepage design, the login process, or the SDK download. The real most important is the Product API documentation! If no one knows how your product is used, even if it is very ingenious, what is the use?

If you are an engineer specializing in product design for developers, writing well-written technical documentation is just as critical as having a good user experience for your end users.

I've seen a lot of things like this, a project that was hastily thrown onto GitHub's page, with only two lines of readme documentation. To be sure, the truly successful API documentation is a work of art that needs to be carefully crafted with love. In the parse product project, we dedicate ourselves to this art!

So what is the key ingredient in making good API documentation?

1. Never hesitate to use hierarchy

Your design document should not simply list all of the terminal functions and their parameters explicitly. A good document should be a complete set of organic system content that directs users to interact with the API through documentation. Step back to 10,000 and say that you have at least the following parts of your document.

Reference index: The reference index should be a exhaustive list of all the functional functions of the red tape. It must indicate all data types and function specifications. Advanced developers should be able to hold it all day as a reference book to use.

Development Guide: This is a document that is midway between the reference index and the development tutorial. It's like a more detailed reference index that illustrates how to use various APIs.

Development Tutorials: The development tutorials will be more specific about how to use the API and highlight some of these features. If you can provide the source code that can compile and run, it would be better.

In the parse project, we did all three of these sections. We are currently working on more development tutorials.

Another good example of this is the stripe ' s API (http://www.stripe.com). The documentation for this product includes a great hybrid guide and reference, as well as a set of development tutorials. The GitHub API reference has also been well designed.

2. Do not include abstract concepts in the examples

You can argue that my API itself is an abstraction, and that abstraction is its hallmark. However, when you are teaching the developer how to use the process, still can not abstract is not abstract better.

Give as many examples as you can in your document. No developer will complain that you have too many examples. In practice, this can significantly shorten the time that developers understand your product. In this case, our website even gives a sample code to explain.

3. Reduce the number of clicks

Developers hate clicking the mouse, which is no secret anymore. Don't spread your documents across tens of thousands of pages. Try to put all the relevant topics on one page.

We are very much in favor of the use of the "single page Large Guide" form of organization ( link ), this form can not only give users an overview of the overall, only through a navigation bar to enter their interest in any topic, there is also a benefit: when the user in the search, just search the current page, Can cover all the content.

A good example of this is ckbone.js documentation, as long as you have a mouse, everything is under control.

4. Include the appropriate quick guide

At the beginning of everything, developers learn a new set of APIs that have to adapt to their new way of thinking and learning is expensive. The solution to this problem is to guide the developer through a quick guide.

The goal of the Quick Guide is to give users the minimum cost of learning how to use the APIs you provide to do small things. That's all. Once the user has completed the Quick guide, they have confidence in themselves and can move on to a more in-depth theme.

For example, our quick Guide allows users to download the SDK and store an object on the platform. To do this, we even made a button to let the user test whether they completed the quick guide correctly. This can enhance the confidence of the users to encourage them to learn the rest of our products.

5. Support for multiple programming languages

We live in a world of many languages. If possible, provide your API with a variety of programming language versions of the sample program, as long as the API supports these languages. Most of the time, multilingual work is done by the client library. It's hard to imagine developers trying to master a set of APIs and leave their familiar programming language.

Mailgun's API has made a good example of this. It offers multiple versions of curl,ruby,python,java,c# and PHP for developers to choose from.

6. Never let go of any border situation

The worst thing you can do to develop an app using the API is that you've found errors that are not mentioned in a document. If you encounter this situation, it means that you cannot confirm whether your program has gone wrong or your understanding of the API is wrong.

Therefore, the reference index must contain the boundary conditions that each hypothesis may cause, whether it is displayed or implicit. Spending a little time on it will definitely do a multiplier effect.

7. Provide sample application

At the end of the study, developers want to see the general blueprint for the application of the project product. The best way to achieve this is to provide a running sample application. I have found that application code is the best way to integrate the operational mechanism of the API with the integration of the system.

The sample code in Apple's iOS Developer Library is a great way to do this, and it includes a detailed IOS sample program, categorized by topic one by one.

8. Join the Human Factor

Reading technical documentation is tedious, and naturally not as stressful as a roller coaster ride. However, you can at least by adding some human factors, or joking. Give your example a variable with some fun names, don't always call the function name Foo or something, so your readers feel refreshed.

At the very least, this will ensure that your readers will not go to sleep while reading.

Conclusion:

To be popular, a good design document is essential. However, designing a good document requires a lot of input to form. However, these inputs are worthwhile because their significance is as important as the product itself.

The other half of the recipe for good documentation is to work in that direction from the initial stage of product development. However, this is not the scope of this article to discuss.

How programmers write good technical documentation how to write high-quality API documentation work