Software Development, Technical Writing
How To Write Technical Documentation For APIs
One of the threads on LinkedIn is how to write technical documentation for APIs. It’s been many years since I’ve documented an API (Java & Oracle) so if you have any thoughts on the best way to do this, then please jump in.
An application programming interface (API) is an interface implemented by a software program to enable interaction with other software, much in the same way that a user interface facilitates interaction between humans and computers.
What is an API?
APIs are implemented by applications, libraries and operating systems to determine the vocabulary and calling conventions the programmer should employ to use their services. It may include specifications for routines, data structures, object classes and protocols used to communicate between the consumer and implementer of the API. Wikipedia
Concept
An API is an abstraction that defines and describes an interface for the interaction with a set of functions used by components of a software system. The software that provides the functions described by an API is said to be an implementation of the API.
An API can be:
Generic — the full set of API that are bundled in the libraries of a programming language (e.g. the standard Template Library in C++ or the Java API)- Specific — meant to address a specific problem, like the Google MAPs API or the Java API for XML Web Services.
- Language-dependent — available only in a given programming language. It is only available by using the syntax and elements of that language to make the API convenient to use in this context.
- Language-independent — written in a way that means it can be called from several programming languages. This is a desired feature for a service-oriented API that is not bound to a specific process or system and may be provided as remote procedure calls or web services.
For example, a website that allows users to review local restaurants is able to layer their reviews over maps taken from Google Maps, because Google Maps has an API that allows it. Google Maps’ API controls what information a third-party site can grab, and what can be done with it.
“API” may be used to refer to a complete interface, a single function, or even a set of multiple APIs provided by an organization. Thus, the scope of meaning is usually determined by the person or document that communicates the information.
API Guidelines
Here are some sites that offer guidelines and examples of API documentation.
- API Writing – http://api-writing.blogspot.com/
- Dustin Diaz, API Writing Tips – http://www.dustindiaz.com/api-writing-tips/
- Rajeev Jain, Developing your First API Guide – http://www.stc-india.org/conferences/2006/agenda_web.htm
- Sun API Documentation – http://java.sun.com/j2se/1.4.2/docs/api/
- API Documentation Trends and Opportunities – http://www.stc-india.org/conferences/2004/PprPrest/Conf_Rajeev.htm
- Susan W Gallagher, What are APIs and SDKs – http://members.cox.net/susanwg/susanwg/api.html
- Generating API documentation in HTML format – http://java.sun.com/j2se/javadoc/index.jsp
Twitter’s API Documentation
Twitter has done a great job documenting its API and breaks out all the different component.
“The Twitter API consists of three parts: two REST APIs and a Streaming API. The two distinct REST APIs are entirely due to history. Summize, Inc. was originally an independent company that provided search capability for Twitter data. The Streaming API is distinct from the two REST APIs as Streaming supports long-lived connections on a different architecture.” http://apiwiki.twitter.com
Tips for writing API documentation
What advice would you give to someone writing their first API document set? What mistakes do technical writers make when approaching this area?
FYI: Twitter API: Up and Running: Learn How to Build Applications with the Twitter API
Great post, very informative.
Is API Documentation being outsourced to India and China at the same rate as other forms of Technical Writing? I am considering learning some programming languages to be able to write API as well as traditional manuals.
Hello Yaakov,
Most of the US IT firms seem to prefer India as there are many Indian developers there already, so the hand-over is easier.
Whereas in Europe it’s going to Poland. Their workforce has great English skills and many start in Ireland or the UK and then head back home.
China is far behind as they have no English language skills, even the graduates are pretty weak. And getting work permits here can be problematic…
Ivan
Forgot to say that the more technical your skills are, the better placed you'll be to get work.
Oracle, Websphere, SAP are all worth looking at.
Avoid open source – very little money in it.
Look at CRM, ERP systems that corporate use – big money there.
Ivan, you can also add EDA, Telecom, Networking, Semiconductor, and Embedded. Demand in much more than supply, so all the best.
I wouldn't say that there is “very little money” in open source, so much as that the jobs are hard to find (but pay market rates if you can get them). An increasingly popular business model is for a company to open-source their core product, and then charge for support, customization, integration, etc. Those products tend to be enterprise systems that corporations want to pay for support of. They must be integrated with other systems, and so have APIs that need documentation. Even though the vendor is trading on their expertise with the product, they need good documentation in order to grow the user base that they draw customers from.
Also, volunteering on open source docs can be a way to build a portfolio to break into the job market. It could provide impressive evidence that you know how to work with software developers and use their tools.
I agree with Janet to some extent that open source projects helps you to build your portfolio and also learn from the professionals. This way you to increase your market value and network too. Yes, open source jobs are difficult to find and you as an individual should dive in deep to even find that job.
Financial Services is where I've made the most money, esp on contracts. Budgets are not usually a problem – it's getting the job done. Semiconductor is a winner too. Working at Intel is a great way to learn how to write docs. All the structures are in place. Thanks Rajeev.
Time is money. I can’t afford (literally) to wait for work to come in. When I worked in SFO, I’d often do two contracts at the same time, i.e. one on-site & one at home or later both at home.
<I wouldn't say that there is “very little money” in open source, so much as that the jobs are hard to find
I think that’s the problem I had. I got tired to looking for this work, instead I focused on IBM and Oracle products and made the money here.
<but pay market rates if you can get them.
Again, I don’t want market rates. I want the highest rates I can get and open source doesn’t let me realize this aim. Maybe it’s different for others but the big money has been with the big players.