Documenting APIs and SDKs

Question: What should I consider when documenting APIs and SDKs? Are there any good resources out there? Things to Consider: Typically, you just need to identify all the different function calls (methods), what the parameters are, etc. A good example of this is the Java Programmer's Reference guide (Grant Palmer). Though it's not exactly an API book, it might be a good example of what needs to be written. He lists each type of function call, explains how each function works, explains the input parameters, and shows examples for using the function. The legwork you do with your SME(s) is more critical with APIs than with other product documentation. Unless you're able to read the code yourself and figure out what they did (code comments?), all of your content has to come from the developers. Even if there are specs, there's no telling if the final product actually matches the specs. Start with a list of the APIs to document (this is actually one of the hardest and potentially politically charged aspects of the project). Get your developer and/or product manager to list all of the APIs (or Java methods?) to be documented. The developer has to comb through all of the code and produce the list. Then the developer needs to verify that you actually want to document each of those APIs. Remind your developer to include any APIs that might be included in imported libraries, because these APIs would also be exposed by your product. Here's where it gets tricky though. Are those imported libraries yours or are they 3rd party libraries? For example, I once had a developer tell me that he imported a class of Sun Java methods (500+ methods) and that I needed to document them "because they're exposed by the product." I had to go over the developer's head to get management buy-in that it's not proper (or legal) to document a 3rd party's product. The next bit of information is the "signature" or attributes of the APIs. You should get this information from the developer at the same time you get the list of APIs. The only reason I think of this as a separate cycle is that the list of APIs is often politically charged, but the signature is very cut & dried. The signature of each API should include information like Name, Parameter(s), and Returns. Add some more bits to this, and you have a fully documented API: Name Description Parameters Returns Comments (or "Additional Information") Example Depending on the style guide you're using, you may or may not already have a pair of Term/Definition styles. If so, you can probably use them for your APIs, like the following examples: myFunction [This is the "Name" of the API. Use whatever heading level is appropriate for the structure of your doc] Description ["Term" style] The myFunction method converts a string to an integer and washes your car. ["Definition" style] Parameters ["Term"] The myFunction method uses the following parameters: ["Definition"] [Insert a table for the parameters. Typically, you'd include a column for the parameter name, type (string, Boolean, etc.), and a description.] Returns ["Term"] true - Returns true if the function was successful. Otherwise, returns false. or string - Returns the name of the requesting function as a string. Example [Insert code sample here] This pattern of "thing" and "description" (e.g. Return and return description) should be consistent throughout all of your APIs, but will be unique for your doc. For example, Java methods would also include a "Throw" and the signature: myMethod(string String1, string String2, int iCounter). So you'll definitely have to tailor this layout to match the environment and language for your product. If you're trying to cost-engineer the project, then get rid of the code samples. The code samples are the hardest part of the API, again because of the dependence on the developer. If you were proficient enough to write your own code samples, then you'd be a developer instead of a writer. Foster a strong relationship with your developer and it should go well. (Don't tell anyone, but the developer does more than 50% of the work on these types of project. Your job is to ensure that the structure/formatting is consistent, that there is no missing information, and that the language is correct--not Chinese or Russian.) Organize the APIs into categories (like Type Conversions, Date and Time, Input Output, etc.). Usually types of functions are contained in separate libraries or classes. Use these categories to create your chapters. List each function alphabetically within the chapter. Where possible, include cross references to related functions. It's OK to relax your grammar when you're documenting APIs. Because this is reference material for developers, it's OK for certain descriptions to be sentence fragments. (I don't know where it is written that APIs use relaxed grammar - it's just that way). Finally, be careful with your copy & paste. Since APIs are fairly repetitive, it's tempting to recycle your material. It's safer to document each function from scratch than it is to copy/paste. A final tip: API's are great candidates for XML-based documentation. If it's automated well, the developer can give you his information in XML directly from comments in the source code. API & SDK Documentation Resources: One man's opinion: Regarding books on APIs, I honestly don't think the subject warrants it's own book. It's like writing a book about how to write a cookbook. There are plenty of good books on writing and plenty of fine examples of cookbooks. It's up to you to connect the dots and apply the writing concepts to the specific topic of APIs. And another's: I agree that API writing is repetitive and easy to do once you get going. However, you also wade into very abstract programming concepts that many writers (especially those with no programming experience or training) have difficulty getting their heads around. API training is very useful to understand what programmers want and need, and how to write for this audience. Examples of API documentation: Online help for Excel. Look up the help for one of the functions that has multiple parameters (like COUNTIF). Their help will give you an idea of the flavor of an API doc. Manuel Gordon's course "Documenting APIs and SDKs." It is available on DVD (http://www.gordonandgordon.com/). If you are documenting Java classes/methods, then you should consider using the Sun Javadoc utility to create and deliver HTML javadocs. This group discusses docs for APIs and SDKs quite a bit: http://groups.yahoo.com/group/nettechwriters/