By Leah Scampoli
A few months ago, I was placed onto a new project at work: API reference documentation. It’s been challenging, rewarding, confusing, and frustrating–all at once.
I’d never worked on API documentation before, which I don’t like to admit in the company of other technical writers who seem to all be experts in this arena. But, for whatever reasons, I’d mostly worked with consumer documentation, no less technical or difficult, but definitely different. It’s only been the last couple years that I’ve edited developer documentation or written instruction sets for developers. But, never traditional API reference information.
I was lucky enough to be put on the project at work and have the support of an amazing team of product managers and developers to work with, who understood my inexperience writing this type of documentation but had enough faith in me to still produce high-quality documentation without putting too much of a burden on them.
Early on, I started researching how other companies were presenting their API reference documentation, both to get an idea of what was required and to compile some best practices. Together, the team and I identified Amazon Web Services and eBay as having some really great examples. It made sense given that these companies are large and well-established that they would have the resources to devote to documentation. Although smaller, start-up type companies tended to not have such polished documentation, it was always a pleasure to come across a company that had clearly prioritized documentation.
With so many great examples, it was a fun process to pick and choose the best ideas to use in our documentation. As this was a new service and there was no API reference model so far, I had the unique opportunity to create documentation from scratch, without any constraints on consistency or style. This allowed me to create something that was user driven.
Of course, this was only possible because of the great support from the team. Not only did they make the time to review the documentation, they provided really insightful feedback on what a developer would–and wouldn’t–need and like to see in the documentation. It was refreshing to work for a team that understood the importance of documentation. For instance, time was taken to perform usability testing on the tutorials. I’d always heard of, but never thought I would be part of, such type of invaluable, but rarely realized, documentation testing.
That’s not to say that there haven’t been challenges. It was difficult to learn everything about API documentation in a short period of time. Learning new terminology, new tools, and the basics of programming was something I always knew was part of technical writing, but something I hadn’t yet come across in my career.
Sometimes I was confused and frustrated that I wasn’t getting it quicker. But, with a little patience and yogic breathing, I was able to finish the documentation on time for the first, major milestone. It’s in no way complete, and there’s a lot to add. But, it’s been no less rewarding to hear compliments and congratulations.
I’m really appreciative that I had such a great first experience with API reference materials, and I look forward to expanding and building upon what I’ve learned to create even better documentation.