How to Compile High-Quality API documentation

Writing technical documents is one of the daunting tasks for many developers. It is a time-consuming and laborious task. But most of the time, people always want to copy shortcuts, and the results are often very regrettable, because quality technical documentation is an important factor that determines whether your project attracts attention. This is true for open-source products or developer-oriented products. In fact, what I want to explain is: for developers, the most important part of the user experience is not the homepage design, login process, or SDK download. The most important thing is the product API documentation! If no one knows how to use your product, how can it be used even if it is a tough task?

If you are an engineer specializing in Product Design for developers, writing complete technical documents is just as important as providing a good user experience for end users. (API design is a smart investment, and your return is a loyal developer. For details, see why "developer friendliness" is the core of API design.)

I have seen many similar cases where a project was flushed to the GitHub page with only two lines of readme instruction files. You must know that the truly successful API documentation is a work of art that needs to be carefully prepared by love. In the parse product project, we dedicate ourselves to this art!

so what are the key factors for Creating Excellent API documents?
1. never hesitate to use layers
your design document should not simply list all terminal functions and their parameters. A good document should be a set of organic system content that can guide users to interact with APIs through documents. Step 2: Make sure that your document contains at least the following parts.
reference index: the reference index is a list of all functions. It must indicate all data types and function specifications. Senior developers should be able to use it all day for reference books.
Development Guide: This is a document between reference indexes and Development tutorials. It seems to be a more detailed reference index, clarifying how to use various APIs.
development Tutorial: the development tutorial describes how to use APIs in more detail and focuses on some of the functions. If you can provide the Source Code that can be compiled and run, it would be better.
In the parse project, we have done all three of the above. At present, we are working on more development tutorials.
another outstanding example in this regard is Stripe's API (http://www.stripe.com ). This product documentation includes a great hybrid guide and reference and a set of development tutorials. GitHub api reference has also been well designed.
2. do not include abstract concepts in the example
you can argue that my API itself is an abstract body, and abstraction is its characteristic. However, when you teach developers how to use it, it is better not to abstract it without being abstract.
in your document, let's give examples as much as possible. No developer will complain that you have too many examples. In fact, this approach can significantly shorten the time for developers to understand your product. In this regard, our website even provides an example of Code .

3. Reduce the number of clicks
Developers hate mouse clicks, which is no longer a secret. Never scatter your documents Across tens of thousands of pages. Try to put all related topics on a page.
We strongly recommend that you use the organization form (Link) of the "single page guide", which not only allows users to view the global information, but also allows users to access any topics they are interested in through a navigation bar, another benefit is that when you search for the current page, you can only search for all the content.
A good example in this area is ckbone. js documentation. Everything is under control as long as you have a mouse.

4. Include the appropriate Quick Guide
Everything starts hard. Developers/ Program When learning a new set of APIS, you have to adapt to the new way of thinking, which is expensive to learn. The solution to this problem is to guide developers through quick guides.
The Quick Guide aims to help users learn how to use the APIS you provide at the minimum cost. That's all. Once the user has completed the Quick Guide, they have confidence in themselves and can move towards a more in-depth topic.
For example, our quick guide allows users to download sdks and store an object on the platform. To this end, we even made a button for users to test whether they have completed the Quick Guide correctly. This improves user confidence and encourages them to learn other parts of our products.

5. Support for multiple typesProgramming Language
We live in a world of multiple languages. If possible, provide sample programs of various programming language versions for your API, as long as the API supports these languages. Most of the time, multi-language work is done by the client library. You know, it is hard to imagine that developers need to master a set of APIs and leave their familiar programming languages.
The mailgun's API has set a good example for this purpose. It provides curl, Ruby, Python, Java, C #, PHP, and other versions for developers to choose from.

6. Never let go of any boundary
The worst case you can encounter when using APIs to develop applications is when you find an error that is not mentioned in the document. If you encounter this situation, it means you cannot determine whether your program is wrong or whether you understand the API is wrong.
Therefore, the reference index must contain the possible boundary of each hypothesis, whether displayed or implicit. If you spend some time on this, you can definitely get twice the result with half the effort.

7. Provide sample applications
At the end of the study, developers hope to see a general blueprint for project products and applications. The best way to achieve this is to provide a running sample application. I found that application code is the best way to integrate the API running mechanism with the system.
Sample Code in Apple's iOS Developer Library is well done in this regard. It contains a detailed IOS sample program and is classified by topic.

8. Add human factors
Reading technical documents is boring and naturally not as intense as riding a roller coaster. However, you can at least add some human factors or joke. Let's give your examples some of their variable names. Don't always put the function name Foo and so on, so that your readers will have a new look. At least, this ensures that your readers will not go to bed while reading.

Conclusion:
A good design document is essential if you want to be deeply rooted in the hearts of the people. However, designing a good document requires a lot of investment. However, these inputs are worthwhile because they are equally important to the product itself.
The other half of writing good documents is to work in this direction from the initial stage of product development. However, this is not the scope of this article.

Original ENGLISH: James Yu Compilation: bole online-Huang Xiaofei