Recent Comments

API and SDK documentation: Notes from Ed Marshall's Workshop at Information Development World

I had the opportunity to attend Ed Marshall's API and SDK workshop at Information Development World. These are my notes.

APIs versus SDKs

SDKs are a set of tools that developers can use to make it easier to work with an API. Ed said that at one company, the SDK was a GUI tool of some kind that made it easier to interact with the company's API. (When I worked at Badgeville, our JavaScript SDK made it easy to work with the REST API through a JavaScript format.)

In contrast, APIs are the under the hood stuff — the functions, methods, and classes that make the system work.

Audience

APIs are typically written for developers, so you don't need to include a lot of handholding.

API characteristics

API writing tends to be formulaic, boilerplate. The format and organization is very consistent. Users will expect this consistency. They want a “just-the-facts-ma'am” kind of experience. Here's an example of common elements for each class/function etc.

API Class name

short description

long description. (If it's obvious what the class does, try to add some additional information about it that isn't so obvious. For example, if the class is openFile, you might add whether the file is open for read/write access or not.)

parameters

example

return value

comments

see also

The API topic typically has a sentence fragment that tells what the component does, e.g., “Opens a help topic in a specified help window.” Try to start the short description with a verb. The description can be a fragment. Just get right to the point in a very simple way.

The short description is followed by a lengthier description if needed. (The short description is delimited by a period, so after the period, the Javadoc parser will treat the next section as the lengthy description.)

The description is followed by a table or list of parameter names.

After the parameter list, you show an example of how it works.

Then list any return values.

Finally, add any comments that point out special notes and such.

Mini table of contents

Often a package or interface has a group of methods in it. The mini toc gives you an overview of everything that can be done in that package. Each of the methods links to more detail.

Search versus index

An attendee asked, What if developers just want to search for things on Google? How do you handle that?

Ed said people can't find something if they lack the right vocabulary to find it. Additionally, a good index can provide cross-references that helps people find information in more efficient ways.

A lot of API documentation is not going to have an index. It's often a nice-to-have feature that's not done. Cheryl Landes, Ed's assistant during the workshop, is a strong proponent of indexes, and said that people often don't use them because they don't know how to use them. Cheryl builds her indexes as she goes.

How much programming do you need to know?

If you're applying for a programmer writer position, then yes, you do need to know how to code. (Programmer writer positions are basically developers who have turned toward writing.) But if not, then you won't need to become a professional developer.

You do need to know some programming basics, but you don't need to have advanced programming capabilities. You just need to be familiar with concepts and terms.

Are API docs translated?

More often than not, API docs aren't translated. Most programmers who speak languages other than English learn programming in English anyway.

Key programming concepts

Date types and variables

Program controls, such as loops, conditions, etc.

Logical operators

Data structures, such as arrays

Functions and methods

You don't need to concern yourself with the inner workings of the API code. All of this code is hidden from the user. The user is limited by the number of calls he or she can make. You can't change any of these things.

As an analogy, he said a person who owns a car can add oil, test the battery, etc., but you don't have access to the inner workings of things like the alternator or pistons.

Java Internal/External Functions

Public: exposed via compiled .jar files to users.

Example:

public class TicTacToe

Private: do not document. Private classes do not appear in the .jar files.

Example

private String last date; // String to hold date displayed

Javadoc

Javadoc is a tool that extracts comments from the code and outputs browser-based help. It's been around since 2000 (at least). It's not super sexy, but it's a default standard for Java developers. It helps provide a thorough, complete, and useful set of documentation.

It's free, still under development, and provides quite a few features that the big name commercial tools don't provide.

Javadoc has an auto-generated index that is really helpful.

Javadoc comments

Javadoc uses the @ symbol in code comments to trigger certain sections in the documentation, such as @param for parameters, @throws for exceptions, and so on.

Ed says that it's common for error messages to be copied and pasted for different functions. Also, a lot of times the functions aren't alphabetized. In other words, a tech writer can contribute.

Javadoc also checks whether the code is valid as it autogenerates the documentation. For example, if you have a class that looks like this:

Your parameters that you document must match up with the actual code. Also, your parameters must be documented. Otherwise, when you run Javadoc, you'll generate an error.

Likewise, if you have @throws APIException in your documents, then you need to have an APIException in the code.

All Javadoc comments precede what they describe. The format of the comments looks like this:

/**
*
*
*
*/

The syntax is like regular code comments but with an extra asterisk at the top.

You can use standard HTML tags within your Javadoc comments, such as

and

tags.

Working with source code

An attendee asks, Are developers afraid that you'll break their code by editing it?

Answer: Absolutely. But they start to get more comfortable with you as you go along. Once you start integrating into their workflow, you gain a lot of street credibility with the team. You begin to be perceived as a member of the team rather than just a wordsmither.

We do operate under the handicap of being a tech writer, not knowing what we're doing. We have to prove ourselves. As you edit the code, you'll often find errors. This can be helpful.

In other jobs, Ed says that people have been much more willing to allow him to edit the code.

Ed also said that he does a test build in a sandbox to make sure that his edits don't break the build.

Javadocs engine

The Javadocs engine comes by default with the JDK, not necessarily the IDE.

From scratch or editing?

An attendee asks whether you always start with some base comments and you clean up, edit, etc. existing content? Or do you ever write it from scratch?

Ed says the former is much more common. You can spot jargon, determine whether something makes sense, identify organizational issues, spot missing information, gaps, etc. You might not be able to really understand the code but you can still contribute positively your feedback based on what makes sense to you.

Percent of time outside of writing/editing?

An attendee asks how much time he spends checking out the build, re-building, etc., versus just writing and editing?

Ed says about 10%, but he has worked with source control a lot. He says he relates really well to source code control paradigms. But if you're not that used to source control workflows, it might take up to 30% of your time to get comfortable with it.

Activities

We did some hands-on activities in adding comments to java files using the right syntax (@param, @exception, and @see) and then generated the Javadoc.

People installed Netbeans and the JDK in order to generate Javadocs. I used Eclipse. Ed had really detailed instructions for everyone to install Netbeans and the JDK for both Windows XP and Windows 7. Even so, there were a few technical issues people struggled with.

Web services - a growing area

A web service is “an application that provides a Web API to provide a platform/language independent application.”

Many of the big web sites online such as Google, Twitter, Flickr, Facebook, YouTube, etc. all have web services that allow developers to interact with their service, such as adding Like or Follow buttons.

Two of the common protocols for web services are REST and SOAP. But there are also XML-RPC and JSON-RPC services.

Format for REST Commands

REST APIs have four main commands:

GET

POST

PUT

DELETE

An attendee asks, what's the difference between REST APIs and RESTFUL APIs. Response: They're the same.

WADL is a web application description language. This is a machine-readable XML description of REST web services. WADL is the REST equivalent of SOAP's Web Services Description Language (WSDL). Most people prefer API doc over WSDL or WADL files.

XML-RPC is oleo than soap and uses a specific XML format. JSON-RPC is like XML-RPC but uses JSOn instead.

Documentation tools for web services

Ed says there aren't many, but here are two:

Adivo (advivo.com)

Sphinx documents python code (sphinx-doc.org)

Hands-on activities with web services

He decided to use Twitter for the hands-on activity. He modeled the template for REST APIs from their site. Ed often gives developers a Word template with blanks to fill in, and they send it back. Other times he may sit down with developers to go over these details.

The sample format for REST API docs had the following sections:

Description

Resource URL

Resource information

Parameters

Notes

See also

Example request

Example result

Processes

An attendee asks, What if I have a process involving multiple functions in a specific order? How do you document that? Ed recommends referencing a flowchart that shows the workflow.

Another attendee asks, So the documentation for REST APIs isn't in with the source code? Ed says no, the doc isn't in the code. It is easier to drift if the code and doc are separate, though.

I'd Rather Be Writing Newsletter

About Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.