API Documentation: Trends and Opportunities
Rajeev Jain (M.Sc., M.B.A.)
Due to rapid growth in companies engaged in software product development, the volume of API documentation has increased considerably in recent years. API documents help customer to customize an application.
Good API guides help companies save a lot of money in terms of support services and companies have realized that they need the services of professional technical writers for API guides. Individuals responsible for creating API guides must be highly skilled in their ability to transform volumes of technical jargon into easy-to-follow end-user workflows.
The demand for API writers is increasing. To become an API documentation expert, you are not required to be a FrameMaker, RoboHelp, Doxygen, or JavaDoc expert. But you must have an analytical mind, basic programming skills, and a desire to explore and learn new technologies.
This paper includes the basics of API guides and also covers the topics, such as:
- current API documentation trends
- skills required to write API guides
- auto-generation tools available
- opportunities available for technical writers
- challenges
Introduction
Among the first lessons for technical writers is “Whatever you see, document it”. Technical writers are expert in documenting the things they see. But can you imagine documenting something:
- which you can’t see easily
- without any GUI
- without any screenshots
- written very systematically with limited number of words
- for which you need to brush up with programming skills
If yes, then get ready for the high salaries, as you could be among those who will be contributing as an application programming interface (API) writer.
API is an interface used by programmers to customize an application. It is an interface through which the user interacts with your software and in not user friendly.
Purpose
The purpose of this paper is to:
- create awareness for API writing
- look into the need for API guides
- discuss the API documentation process and contents required
- explore the current trend and practices followed to write API guides
- explore the skills and knowledge of tools required to master the art of API writing
- discuss auto-generation tools and their limitations
- explore the opportunities available for technical writers
API documentationAn API is required to customize the working of an application. API guides are used by programmers and other professionals only. Sometimes, these guides are also used by students.
Skills RequiredThe basic skills required to master the art of API writing are:
- Ability to understand languages like C, C++, Java, VB.NET, etc.
- Basic understanding of programming concepts
- Ability to understand code, functions, methods, classes, etc.
- Ability to think like a programmer
The basic understanding of Unix or Linux operating system and the man pages
(help provided by Unix and Linux operating systems) will be an added advantage.
Current Trends
Generally, but not always, API documents are written by programmers and SMEs. Technical editors edit these documents for grammar, punctuation, and style-related issues. Finally, tools like Javadoc and Doxygen are used to generate the required output.
Until recently, the volume of API documents was not very high and since these documents were meant for high-tech professionals only, no one really bothered much about the overall quality. But the trend is changing and companies have realized the importance of the presentation and overall quality of these guides. This change provides an opportunity to all technical writers. For this, we must update ourselves with basic skills required to write API guides.
Auto-generation tools
Auto-generation tools are used with source code files to generate the API guides. Auto-generation tools are helpful in freezing the contents (from the source code files), written by the developers and SMEs, based on the template designed by you. These tools must be customized according to the needs and requirements of the users.
There are a few limitations with these tools, such as:
- No direct contribution from technical writers
- Language inconsistency
- They do not provide great look and feel options
opportunites And challanges
As discussed previously, the API documentation has increased considerably due to rapid growth in companies engaged in software product development. This provides both opportunities and challenges to all the technical writers such as:
- Technical writers will be required to brush up on the skills required to write the API guides
- Technical writers with programming skills will be in demand
- Developers with good writing skills may switch to this field
- Technical writers with domain experience will be in demand
Summary API writing is not a very new field for Indian TWs but we don’t have a large database of API writers. The demand for API writers is increasing due to rapid growth in software product development companies in India. We must be ready to grab this opportunity. To master the art of API writing:
- Learn the basics of at least one programming language
- Learn tools like Doxygen, JavaDoc, Help2Man, Mif2man, Text2man
- Understand the basic programming concepts
- Familiarize yourself with the Unix operating system and the man pages (optional)
Once you are comfortable with API guides, you can also contribute in the programmer’s manuals.
Finally, good news for all budding API writers: salaries are often on par with developers and may be even higher.
Rajeev Jain
Lead Technical Writerrajeevjain@vsnl.com
rajeevjain72@gmail.com
Mobile: 091-93141311170
(The author has over twelve years of IT experience. He has worked as programmer and system analyst with organizations like W.H.O. and DBS Bank (Singapore). He has written books titled Y2K and India, Informatics Practices, and others. He has organized seminars and workshops on topics such as “Software Engineering”, “Visual Basic”, “C”, “FoxPro”, “Y2K Scenario”, and many more.)
