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.”

Writing documentation in an Agile environment

Agile was created by and for developers, and documentation does not fit naturally into its processes. Doc managers need to be proactive about integrating writing into the process. In my experience, doc departments take too passive a role.

Here are some of the difficulties with putting tech writers on Agile teams:

• For much of the Agile process, the software is not finished enough for writers to begin working on it. If writers start writing before a feature is complete, they may have to do a lot of rewrites. This can be a time waster. It can also lead to mistakes in the end process, especially if aspects of the feature are mentioned in several deliverables.
  
• Depending on the writing requirements of each Agile project, a writer might need to be part of multiple projects. I was once on seven active Agile projects at the same time. It's not feasible for a person to attend seven daily standup meetings, even if they're only 15 minutes each.
  
• Agile is designed to get developers to act as teams, so it includes every Agile project member in scoping and other team decisions. It is not necessarily useful for writers to participate in those decisions.

When figuring out how to fit into Agile, doc teams should keep the goals of Agile in mind. See your company's Agile evangelist for details for your company, but my initial list of goals would be to empower employees, create super-functional teams, reduce useless bureaucracy, create user-focused output, and respond quickly to market needs. Doc managers should go to the team that organizes Agile in their company and provide that team with some rough requirements for integrating writers into Agile. After that, it's a matter of working with the Agile team to finalize a list of goals, requirements and rules for writers. (There might be different sets for different levels of writer.) Every context has its own needs, but here are some sample doc goals, requirements and implementation rules. (Note that this is not intended to be a complete or cohesive set; plus, ideally the goals, requirements and rules should align.) Sample goals:

• Writers should have more and better communication with developers.
  
• Writers should have a thorough understanding of users, the market and the product.

Sample requirements:

• If there are no product specs, the writer needs comprehensive use case scenarios, a working sample to test, etc.
  
• The doc manager will not be on the Agile teams, but needs to evaluate and prioritize resources.
  
• Writers should sit with the developers on their Agile project.
  
• Writers should review terminology and usability issues early in the design phase.
  
• During the project, writers should review resource strings (error messages, UI text, etc).
  
• Writers {need to | should not} participate in multiple Agile projects at the same time.

Sample Agile implementation:

• If a senior writer is on an Agile team, the writer should assist the Product Owner with the creation of user stories.
  
• Writers should attend only review meetings until they start writing.
  
• Writers should start writing when the feature is complete, stable, and has been tested.
  
• Writers should write throughout the process, documenting every iteration.
  
• Writers should work one iteration behind the rest of the Agile team.
  
• The writer should be considered a Stakeholder for the project.

Re the requirement that writers will begin documentation only when a feature is complete and tested, Development may want iterations of the product to be documented for internal testing or other reasons, which is fine - but may require more writers. In addition, if a company wants to continuously deliver software updates with docs - and do it at a lightning fast pace - they might have to realize that doc productivity will fall and they'll need more writers.

I think the reason that doc teams aren't proactive enough in stating their requirements is the way that Agile is often introduced. There is a lot of emphasis on denouncing other processes, assimilating employees, and broaching no dissension. (This is a lot like the way DITA typically gets introduced.)

Agile evangelists (like DITA evangelists) frequently feel that the most important issue is employee attitude, and they are overly sensitive to anything that might be considered negative. But docs simply aren't an easy fit for Agile, and it's important to figure out where the problems are before devising a solution. All too often, writers are just made members of Agile teams and left to muddle through - which usually doesn't work very well.