How to create high-quality API documents
Source: Shangpin China |
Type: website encyclopedia |
Time: March 9, 2012
Beijing website construction Company Shangpin China: To write technical documents is to make many Website production One of the daunting tasks for developers. It is a job that takes time and effort to do well. But most of the time, people always want to copy shortcuts, and the results are often very regrettable, because high-quality technical documents are an important factor in determining whether your project is attracting attention. This is true for both open source and developer oriented products. In fact, what I want to say is that for developer oriented products, the most important part of their user experience is not home page design, login process, or SDK download. The most important thing is the API documentation of the product! If no one knows how to use your product, even if it is ingenious, what's the use? If you are an engineer specializing in product design for developers, it is just as important to write perfect technical documents as to provide good user experience for end users. I have seen many similar situations where a project is thrown carelessly onto the GitHub page with only two lines of readme description files. You should know that truly successful API documents are artworks that need to be carefully made with love. In the Parse product project, we have dedicated ourselves to this art! So, what is the key factor in making excellent API documents? 1. Never skimp on the level of use Your design document should not simply list all terminal functions and their parameters. A good document should be a complete set of organic system content, which can guide users to interact with APIs through documents. To say the least, you should make your document include the following parts. Reference index: The reference index should be an exhaustive list, including all the red tape of function functions. It must indicate all data types and function specifications. Senior developers should be able to use it as a reference book all day long. Development Guide: This document is intermediate between the reference index and the development tutorial. It is like a more detailed reference index that illustrates how to use various APIs. Development tutorial: The development tutorial will more specifically explain how to use the API, and focus on some of its functions. It would be great if you could provide source code that can be compiled and run. In the Parse project, we have achieved all three parts mentioned above. At present, we are working hard to prepare more development tutorials. Another excellent example of this is the Stripe's API（ //www.stripe.com ） 。 The product documentation includes a great Hybrid Guide and Reference and a set of development tutorials. The GitHub API Reference has also been well designed. You can argue that my API itself is an abstraction, and abstraction is its feature. However, when you teach developers how to use it, it is better not to abstract. Give as many examples as possible in your documentation. No developer will complain that you give too many examples. In fact, this approach can significantly shorten the time for developers to understand your product. Our website even provides a code sample to explain this. 2. Reduce the number of clicks It is no secret that developers hate clicking the mouse. Don't scatter your documents among tens of thousands of pages. Try to put all relevant topics on one page. We are very much in favor of using the organization form (link) of "single page guide". This form not only allows users to overview the whole situation, but also can access any topic they are interested in through a navigation bar. In addition, it has the advantage that when users search, they can search the current page, covering all the contents. An excellent example of this is ckbone.js documentation. As long as you have a mouse, you can master everything. It's hard to start. Developers have to adapt to their new way of thinking after learning a new set of APIs, which is costly. The solution to this problem is to guide developers through quick guides. The purpose of the quick guide is to let users learn how to use the API you provide to do some small things with minimum cost. That's it. Once users complete the quick guide, they have confidence in themselves and can move forward to a more in-depth topic. For example, our quick guide allows users to download the SDK and store an object on the platform. To this end, we even made a button to let users test whether they have completed the quick guide correctly. This can improve the confidence of users to encourage them to learn other parts of our product. 3. Support multiple programming languages We live in a multilingual world. If possible, provide sample programs in various programming languages for your API, as long as your API supports these languages. Most of the time, multilingual work is done by client libraries. It is hard to imagine that developers want to master a set of APIs and leave their familiar programming languages. MailGun's API has set a good example for this. It provides curl, Ruby, Python, Java, C #, PHP and other versions for developers to choose from. 4. Never miss any boundary conditions The worst situation you can encounter when developing applications using API is that you find an error that is not mentioned in the document. If you encounter this situation, it means that you cannot confirm whether your program or your understanding of the API is wrong. Therefore, the reference index must include the possible boundary conditions caused by each assumption, whether explicit or implicit. Spend some time on this, it will definitely get twice the result with half the effort. At the end of the study, the developers hope to see the general blueprint of the project product application. The best way to achieve this goal is to provide sample applications that can be run. I found that application code is the best way to integrate the API operation mechanism and the system. The sample code in Apple's iOS Developer Library does a good job in this respect. It contains detailed iOS sample programs and is classified by topic. 5. Add humanistic factors Reading technical documents is boring, and naturally it is not as exciting as riding a roller coaster. However, you can at least add some humanistic factors or make jokes. Give some funny names to the variables in your example. Don't always call the function name foo or something, so that your readers will have a new feeling. At the very least, this ensures that your readers will not fall asleep while reading. This article was published on Beijing website production Company Shangpin China //ihucc.com/
Source Statement: This article is original or edited by Shangpin China's editors. If it needs to be reproduced, please indicate that it is from Shangpin China. The above contents (including pictures and words) are from the Internet. If there is any infringement, please contact us in time (010-60259772).
