Abbre­vi­a­tion of appli­ca­tion pro­gram inter­face, a set of rou­tines, pro­to­cols, and tools for build­ing soft­ware appli­ca­tions. A good API makes it eas­ier to develop a pro­gram by pro­vid­ing all the build­ing blocks. A pro­gram­mer then puts the blocks together.

Most oper­at­ing envi­ron­ments, such as MS-Windows, pro­vide an API so that pro­gram­mers can write appli­ca­tions con­sis­tent with the oper­at­ing envi­ron­ment. Although APIs are designed for pro­gram­mers, they are ulti­mately good for users because they guar­an­tee that all pro­grams using a com­mon API will have sim­i­lar inter­faces. This makes it eas­ier for users to learn new programs.

What are the com­mon tools used?
Tools used for doc­u­ment­ing APIs? Framemaker (or, in some cases, Microsoft Word) for text for­mat­ting and lay­out. Javadoc (http://java.sun.com/products/jdk/1.2/docs/tooldocs/solaris/javadoc.html#doclets) and Doxy­gen (http://www.stack.nl/~dimitri/doxygen/)and sim­i­lar tools for extract­ing data def­i­n­i­tions and class and method dec­la­ra­tions. Per­haps Visio or other graphic tools to draw UML (Uni­fied Mod­el­ing Lan­guage) dia­grams or flow charts.

API Writer

An API writer is a tech­ni­cal writer who writes doc­u­ments that describe an appli­ca­tion pro­gram­ming inter­face (API). Such writ­ers write for an audi­ence that includes pro­gram­mers, devel­op­ers, sys­tem archi­tects, and design­ers. API Writ­ers pro­duce doc­u­ments that include:

API Ref­er­ence Guides
Programmer’s Guides
Devel­oper Man­u­als
Admin­is­tra­tion Man­u­als
Instal­la­tion Guides

API writ­ers need to under­stand appli­ca­tion code enough to extract the infor­ma­tion API doc­u­ments require. API writ­ers gen­er­ally fol­low (in the US) The Chicago Man­ual of Style for gram­mar and punc­tu­a­tion. Other com­mon tools include Javadoc, which extracts com­ments from Java source code.

Qual­i­fi­ca­tions
Usu­ally, API writ­ers pos­sess a mix of pro­gram­ming and lan­guage abil­i­ties. It’s good to have pro­gram­ming back­ground but again it’s not manda­tory. Many API writ­ers switch from pro­gram­ming or tech­ni­cal writing.

1) Pro­gram­ming back­ground (Knowl­edge of C, C++, Java, Assem­bly, etc.)
2) Knowl­edge of tools like Doxy­gen, Javadoc, or FrameMaker
3) Excel­lent com­mu­ni­ca­tion and writ­ing skills to inter­act with devel­op­ers
4) Expert API/SDK writ­ers can eas­ily become pro­gram­ming writers.

API tech­ni­cal process

This is one of the most impor­tant chal­lenges faced by tech­ni­cal writ­ers or who­ever is inter­ested in mov­ing to API doc­u­men­ta­tion. The writ­ing and eval­u­a­tion cri­te­ria varies between orga­ni­za­tions. It is usu­ally most ben­e­fi­cial for API writ­ers to pos­sess a broad and thor­ough knowl­edge of pro­gram­ming struc­ture and syn­tax, while also being ade­quately capa­ble of under­stand­ing the work­ings of a par­tic­u­lar given appli­ca­tion with a greater level of detail related to the spe­cific classes or inter­faces from which its use­ful­ness derives.

60% of the tasks encoun­tered in the writ­ing process involve ana­lyz­ing, plan­ning, and under­stand­ing the code/functions, while the remain­ing 40% of time would typ­i­cally be spent actu­ally writ­ing and review­ing imple­men­ta­tions. Hence, a very solid under­stand­ing of the process is of key impor­tance to API writ­ers as they fre­quent between plan­ning and imple­men­ta­tion phases. A good foun­da­tion of a vari­ety of pro­gram­ming skills is well com­ple­mented by an abil­ity to com­mu­ni­cate effec­tively, espe­cially when the writer seeks to develop a flu­ent level of under­stand­ing with devel­op­ers. Finally, API writ­ers may also be at least partly respon­si­ble for author­ing prod­uct doc­u­men­ta­tion out­lin­ing and spec­i­fy­ing things like included pro­gram con­tent, meth­ods of imple­men­ta­tion, and many other rel­e­vant details.

Resources

API Doc­u­men­ta­tion
Intro­duc­tion to API doc­u­men­ta­tion
What is API Doc­u­men­ta­tion


Doc­u­ment­ing APIs: Writ­ing Devel­oper Doc­u­men­ta­tion for Java APIs and SDKs
Doc­u­ment­ing APIs and SDKs

Sam­ples:
http://www.phoons.com/john/download/AVSapi.pdf

Share