Helping developers write better API references

Several years ago I gave a presentation to developers at my company about how to write better API references. The goal was to help developers who produced public APIs to write code comments that would be more useful to the mobile app devs who used the APIs.

I started with a quote from senior management about the importance of the API references to the success of our products. At this point and throughout the presentation, I wanted it to be clear that I wasn't just some tech writer spouting off about how to do things: this initiative was important to development management. I constantly threw in quotes from development managers (using their names) to support what I was saying. (I couldn't go so far as to say there was an integrated initiative because there wasn't.)

Next, I sketched the current Pubs team initiatives to improve documentation for the mobile app devs: new web sites for doc delivery that made it more easy to find and use the content; new feedback mechanisms; research of what the app devs wanted; and developer outreach such as the presentation I was giving them.

On the subject of research, I described some recent work I had done. I had gone to a developer conference and conducted a focus group, as well as six round-table discussions; collected questionnaires; and done dozens of usability tests with developers. I had attended a hackathon where I interacted with participants, learning their frustrations and successes. I had also attended a Developer's Day where I talked to prospective app devs about their backgrounds and their interest in using our APIs.

My main take-away from that research, I explained, was that mobile app devs want development to be easy. One of my bullet points was, "They are looking for information that is complete, simple, easy to understand, quick to use, and easy to find." This may seem obvious, but most developers seem to assume that app devs don't want to be told too much - that they can figure it out. In my experience, all too many technical writers in development documentation make the same false assumption. What app devs say is: Spell everything out! Tell me how to do it! As I explained in my presentation, three-quarters of the app devs I talked to were working on multiple platforms, not just ours.

Next I shared some personas of mobile app devs. These were not personas that I had made up, but that I had got from senior development managers. (As I have argued before, I firmly believe that personas should be prescriptive rather than descriptive.)

Finally I got to the point where I could define what a public API reference is, and show some examples from our company. I criticized our current API refs: it was too difficult to create mobile apps with our APIs; app devs were complaining; we had acquired a reputation of not being developer-friendly; the API references were a major source of info for technical writers, so the rest of the documentation was suffering; we were getting too many support calls.

I showed an example of a really bad page from one of our API references and explained what was wrong with it. Then I showed them an example of a really good page and talked about why it was so useful to readers. That led into an interactive session of about 15 minutes where we looked at API references and discussed how to improve them. Although there were about 100 developers in the room, the discussion was lively and very positive.

The rest of the talk was guidelines to improve our processes going forward. I defined responsibilities:

• API developers: Document all the elements of the API as comments in source code.
  
• Tech writers: Review the API reference to help with wording, fix typos and grammar, and note missing content.
  
• Both: Tech writers collaborate with developers to add content and examples.
  

I told them that when they started to write code comments for public APIs, they should ask themselves: What is it? When would this be useful or necessary? Why would app devs want to use it? How do they use it? I said the The API reference should explain: every class, method, parameter, etc; side-effects (what this code will affect and vice versa); and assumptions: always think of the customer. Imagine someone who is busy, doesn’t want to spend a lot of time figuring things out, hasn’t immersed themselves in our environment, just wants a quick answer.

After that I described some of the reasons our company had ended up with poor API references, providing a solution for each issue. For example, one solution was, "Ensure that the API reference is a deliverable. Make the API reference a product requirement. Add the API reference to the Definition of Done."

In the question period at the end, many of the developers provided even more ideas for how to make things better going forward. I ended with a quote: “Poorly documented code? Chances are the problem lies not in your programmers, but in your process.”