Writing API Documentation in an Agile Environment

Guest Author, November 7th, 2013

This guest post comes from Jonathan Fingold, co-founder of SDK Bridge. He has worked in many capacities in the software industry and has written API documentation for devices, protocols and applications.

Agile development has changed how software is developed and documented. Perhaps nowhere is this more true than with API documentation.

In a traditional development environment (“waterfall” methodology), requirements are defined up front in a detailed specification, and then code is created to match that specification. The problem with this approach is that the process of coding often reveals areas of improvement, but getting these improvements back into the specification is difficult. Agile methodologies use iterative and incremental development, where requirements apply only to a short-term “sprint” and then may be modified based on what has been learned.

Writing API documentation for software being created with an agile process can be especially challenging because what is being documented is constantly being changed. Although this is true of software documentation in general, API documentation ups the ante because it often requires a level of detail that goes beyond that of other types of documentation.

When it has worked

My best experience was with a team that initially struggled to document features as they were being developed. The team finally agreed to let the documentation team publish off-cycle by one release. By documenting the previous release, the team was able to write about finished features. This made the writing easier and reduced the amount of developer time required to answer questions. It also helped that one developer and one test contact were assigned specifically to answer questions and handle tech review, which removed much of the scheduling ambiguity.

When it hasn’t

My worst experience was with a team that decided to ramp up both the frequency of sprints and the number of features per sprint. There was only one writer for a team of about 20 developers and five project managers. The developers and PMs were almost always rushing to keep up, and trying to schedule technical reviews with them was nearly impossible. The writing backlog just kept getting bigger.

Part of the problem had to do with one of the strengths of agile: immediate feedback and return. To leverage this strength instead of becoming buried by the changes it can introduce, companies need to have a systematic yet robust document process. Such a process should:

1. Augment the design and test phases

2. Enable the writer to act as a kind of user advocate, asking questions such as: Does a particular API make sense? How does it actually work?

3. Provide a way for writers to report the bugs they find in the API. Writers are well-suited to this role because they are looking at features from a different perspective, and they need to write about every single piece of the API.

Writing API documentation in a team that uses agile can be a tricky process. Make sure it is clear what documentation the team expects to produce each cycle, and make sure the team understands what resources will be needed to meet those expectations. Project managers and developer leads will need to assign resources to writers up front, and writers should speak up as soon as issues arise because documentation challenges can snowball much faster in an agile environment.

Both comments and pings are currently closed.

Comments are closed.

Follow the PW team on Twitter

ProgrammableWeb
APIs, mashups and code. Because the world's your programmable oyster.

John Musser
Founder, ProgrammableWeb

Adam DuVander
Executive Editor, ProgrammableWeb. Author, Map Scripting 101. Lover, APIs.