Before we get to documentation, let’s start with what “API” means. API stands for Application Programming Interface, and it’s a set of protocols that define how two or more software applications communicate and interact with each other. APIs provide a method for developers to pull information into their applications from behind the scenes without user intervention or knowledge.
Among the many types of APIs, Web APIs are the most common—a client (computer) sends a request to a Web service (server), which then delivers a response back to the client. When you shop online using a credit card, the merchant site uses an API to send your credit card information to a payment-processing application for verification. Once your payment information is confirmed, the payment application sends a response back to the merchant site giving the ‘OK’ and completing the transaction.
Companies seek technical writers for their API documentation needs for the same reasons as end-user documentation; many developers are not big fans of writing, and just as many are not very good at it. Technical writers bring an important outside perspective for creating clear and effective documentation, including conceptual material that allows developers to read something that immediately communicates why they should work with an API. Well-written documentation will make it easier for developers to use an API and thereby increase adoption. When asked to rank the most important factors in an API, developers ranked “Complete and accurate documentation” as the most important factor in a 2013 survey conducted by ProgrammableWeb, a website that researches and tracks the API economy.
With the evolution and complexity of APIs across web applications, databases, and operating systems, clear and accurate documentation has become a top priority for businesses that want developers to use their APIs.
By Bronson DeKoning