API-Writing / API-Documentation

API Template

2008-04-22T23:27:00.000-07:00

An API Template must include the following:

Syntax: Syntax (prototype) of API
Description: Detailed description of the API
Parameters (input, output): Details of all the input and output parameters along with description of values that can be passed.
Return Value(s): Details of the values returned by API after execution.

API template may also include all / any of the following:

Synopsis: One line description of the API
Calling Sequence: The order in which an API must be called
Usage Scenario: Expected scenarios where the API can be used
Examples: Most of the programmers makes best use of this place and are expert in copying the examples provided illustrating the use of APIs.
Related APIs: Information on the APIs that could be related to the API being documented
Class / Object/ Method name: Name of class / object / method associated with API
Data types: Any special data type declared only for specific API
Header File: Any header file associated with API
Parent class: Details of any parent class associated with API
Exceptions / Error Messages: Any exceptions or errors that a user may encounter while using the API
Notes/Warnings: Special notes or warnings while using the API
Associations or dependencies (if any)

Sample API Template- Here is the sample API Template for C/C++ language:

API name [Write API name here]
Synopsis [Provide brief description of the API]
Include(s) [Provide name of header files to be included.]
Library / Libraries [Provide name of associated libraries]
Syntax / Prototype [Detailed Syntax of API, here example of C++]
int function(
int param1,
char* parma2,
int* param3)
Description [Provide detailed description of the API along with exceptions (if any)]
Argument(s) [Provide the details of parameters/ arguments]
param1 - param1 description, by default an input parameter
param2 [out] – param2 description, output parameter
param3 [in/out] - param3 description, both input and output parameter
Return Values
ret1 Description of return value
err1 Description of error (Error is also a return value)
Calling Sequence - Provide the flow chart or sequence in which the API should be called, mention if there is any dependency.
Usage Scenario - Provide the usage scenario (details on how to use and when to use this API) of the API and possible error or success conditions and how to tackle those errors.
Example
Example Statement
Example code
See Also / Related APIs
API1 (along with cross reference)
API2

http://coloredwritings.blogspot.com/2007/05/api-session-with-rajeev-jain.html

Resources / Links for API Documentation

2008-03-12T22:15:00.000-07:00

API Writer : Wikipedia

http://en.wikipedia.org/wiki/API_Writer

API Documentation - Trends and Opportunities
http://www.stc-india.org/conferences/2004/PprPrest/Conf_Rajeev.htm

Developing your First API Guide, by Rajeev Jain
http://www.stc-india.org/conferences/2006/agenda_web.htm

API documentation: Wikipedia Definition
http://en.wikipedia.org/wiki/API_documentation

How To Write Technical Documentation For APIs
http://www.ihearttechnicalwriting.com/content-management/how-to-write-technical-documentation-for-apis/4268/
FrameScript Tutorials
http://www.frameexpert.com/tutorials/index.htm

What Programmers Really Want-Manuel Gordon
http://www.gordonandgordon.com/downloads/What-Programmers-Really-Want.doc

What are APIs and SDKs by Susan W Gallagher
http://members.cox.net/susanwg/susanwg/api.html

Source Code Documentation using Doxygen, by Ruchi Kak
http://www.stc-india.org/conferences/2004/SessionInfo.htm

API Writing Tips (Surface level tips for good API writing)
http://www.dustindiaz.com/api-writing-tips/

An Introduction to API Documentation, by Akash Dubey
http://www.stc-india.org/activities/learningsessions/BloreSessions/october/API.PPT

Creating a Linux Manual (man) Page-Subhasish Ghosh
http://linux.omnipotent.net/article.php?article_id=12493

Doxygen
http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc

How to document VB6, VB.NET and ASP.NET projects
http://www.vbdocman.com/

txt2man-Txt2man converts flat ASCII text to man page format.
http://mvertes.free.fr/

Javadoc Tool: To generating API documentation in HTML format
http://java.sun.com/j2se/javadoc/index.jsp

Writing for Programmers
http://www.stc-northbay.org/newsletters/aug00.pdf

Yesterday API was just another acronym; today I have to document one! by Susan
http://members.cox.net/susanwg/susanwg/api.html

How to Write Doc Comments for the Javadoc Tool?
http://java.sun.com/j2se/javadoc/writingdoccomments/

Working with XML: Table of Contents
http://industry.ebi.ac.uk/~senger/xml/docs/tutorial/TOC.html

Links to my API/SDK related presentations

2007-09-30T23:27:00.000-07:00

1. Mar 08 - Your First XML/DTD: STC India Session, Bangalore
http://techwriter.meetup.com/2/messages/boards/thread/4435282

2. Feb 08 - MITWA Yahoo Chat Conference: API Documentation - Best Practices
(Chat transcript is available under files section of yahoo group APIWriters as well as MITWA)

3. Dec 07 - Documenting Your First API Guide: http://rubricate.wordpress.com/2007/11/17/delhi-ncr-stc-regional-conference-december-8-2007-oracle-noida

http://rubricate.wordpress.com/2007/12/

4. Sep 07 - Programming Concepts for Writers (with C++): http://twin-india.org/portal/node/1833

http://coloredwritings.blogspot.com/2007/09/makarand-pandit-and-rajeev-jains.html

5. Apr – 07 - Documenting Your First API: http://twin-india.org/portal/node/905

http://coloredwritings.blogspot.com/2007/05/api-session-with-rajeev-jain.html

6. Feb 07 - Developing your first API Guide: http://twin-india.org/portal/node/684

7. Dec 06 - Developing You First API Guide: http://www.stc-india.org/conferences/2006/agenda_web.htm

8. Dec 04 - Trends in API documentation: http://www.stc-india.org/conferences/2004/PprPrest/Conf_Rajeev.htm

All these PPT / PPS files can be downloaded from Files section of yahoo group APIWriters.

Apart from these, I have also conducted workshops / seminars in various educational institutes on topics like:
-Software Engineering
-Visual Basic
-FoxPro
-C
-C++
-BASIC
-Email Communication
-Resume Writing
-Programming Guidelines
-MS Office
-SQL
-MS-Access

http://groups.yahoo.com/group/APIWriters/

Documenting Your First API

2007-05-23T21:10:00.000-07:00

Details about the presentation - "Documenting Your First API"
(With introduction to programming basics and API writing examples)"

Topics
- Programming basics (sequence, selection, and iteration)
- Basics of API writing,- Skills required to write API guides
- Commonly used template, resources available
- Do's and dont's while working with API guides along with examples of C++ APIs.

Yahoo group APIWriters - http://groups.yahoo.com/group/APIWriters
Orkut community APIWriters - http://www.orkut.com/Community.aspx?cmm=27221500

API-Writing / API - Documentation: Links , Resources, and Presentations

2005-05-23T05:07:00.000-07:00

API-Writing

Current trends and opportunities in API Documentation

2005-05-19T03:00:00.000-07:00

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 documentation
An 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 Required
The 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 Writer
rajeevjain@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.)