API-led Documentation

Last Thursday I attended a riveting, well-organized event about APIs, technical documentation requirements by two Meetup groups in the Bay Area, http://www.meetup.com/API-Craft-San-Francisco/events/233267541/ and I am not being sarcastic!

I surprised myself a bit, having written "riveting" above to describe this event. What was so riveting about it was the quality of the presentations and questions asked, leaving everyone with a deeper understanding of the challenge at hand - well-crafted API documentation. There was palpable tension in the room at the end, each camp, the technical writers and the API writers each proposing a vision of the ideal, one developer asserting that API implementation can change, leaving the documentation in an inevitable sorry state. To this, a palpably experienced writer claimed for the writers camp that we have a way of smoothing things out.

Most agree documentation is a developer task in the beginning, and the boundaries become less clear as the product passes from working idea, to a thing that a person uses out in the wild. At the time the docs are crafted, the users are the product creators (engineers), as well as the technical writers - but writing something worth reading requires a familiarity with product that is both high level and low level, and the other important requirement is good writing, that has been burnished after a few cycles of "dog-fooding" the product as per the documentation.

The problem has been well-explained. Documentation traditionally and by its nature comes later in the game to get a product out the door to the public and scaling this activity with a large team of technical writers is difficult and unwieldy. The smart solution is to involve engineering early and often in the task of documenting the product. As one person deftly pointed out, the spec is used as a template for the product, and this spec in the end comes to conform to the product, completing a loop which is not really a full circle, but a swirl, because the spec ends up in a different state than at inception.

If this passage from dream to reality and back were better solidified in software documentation, we'd be living in a much more reliable tech world. It is always a game of catching up. There is no such thing as getting ahead with the documentation, but planning for the future keeps us less behind, so there is something to work toward besides the docs themselves.