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:
/**
* Opens a remote session.
*@param remoteSessionId Session ID to terminate.
* @throws APIException
*
*/
public void terminateRemoteSession(int remoteSessionId) throws APIException { nTerminateRemoteSession(sessionRef, remoteSessionId);}
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.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.