By Mary Linderman
In this article, I will share some of the lessons that I have learned working as an API writer for the past two years. I stumbled into this role by accident when my employer decided to encourage the customization of its software by offering a comprehensive API to third-party developers. While our documentation team had several good writers, I was the only one at the time who had taken any basic programming classes and I had a strong interest in the backend technology used in our software product.
Holding on to my limited knowledge of Java as a lifesaver, I plunged into the depths of API writing. My mission was to support our API team by writing comments for the class libraries, general descriptions of the API’s underlying concepts, and tutorials illustrating how to use the API. I also worked on adding code samples provided by the development team to our website. With the help of another writer, we pulled off the impossible and posted our first version of the site in time for the release.
Since the first version of the site, we have revisited its content and presentation several times. Each version has involved long, hard hours of work during which I have reassessed my skills and abilities as a novice API writer. Here are some of the lessons that I learned as I have ventured out into the field of API writing.
Talk the Talk
When I started working on this project, the only documentation that existed was a few awkwardly constructed PDFs and some sparsely commented class libraries. My programming courses may not have made me a developer, but they had exposed me to the appropriate technical terminology that I would need to use when describing the programming constructs developed by my team. My familiarity with object-oriented terminology helped me gather information from my development teams since I could formulate focused and clear questions about classes, methods, properties, and other programming elements. I could talk the same talk as my developers, so I required less of their time for background information.
I also believed that the resulting documents had an authoritative and knowledgeable voice that communicated in language familiar to my developer community. Since the text served as the voice of the API, it needed to include the appropriate terms for the target audience. Familiarity with programming terminology also helped me to eliminate slang terms from the documentation, which might not be clear to third-party developers even though this secret language was second nature to my internal development team.
Embed Yourself in the Development Team
While developing our API documentation, my support system was a team of hardworking and technically savvy developers. Although I already had worked to develop rapport with my software engineers, the importance of having a strong and, sometimes, humorous relationship with the team was pivotal to documenting the API features that they built.
I made sure to attend team meetings, participate in team activities, ask questions, and actively listen to their implementation plans. Finding ways to complement or facilitate the development efforts of the team was a constant preoccupation for me during our release cycles. I reviewed specifications and researched technologies used by the team so that I could ask better questions and save the team time by focusing on their current development efforts. Since our organization uses an Agile programming methodology, I made sure to add documentation tasks for the team during sprint planning. I was like gum on the bottom of their shoes.
Whenever possible, I tried to underscore the importance of clear and accurate documentation as a way of showcasing their development work and increasing the accessibility of the API to third-party developers. I knew these efforts were really paying off when the team started coming to me with items that needed documenting and pointing out that we needed to add tasks for documentation during sprint planning.
Play with the Technology
One of the most difficult challenges that I have confronted was obtaining the resources and knowledge to play with the API. I have come to view documenting the API in the same light as writing about UI features. I needed to work with the API by running simple code samples to gain better insights about the user experience. As an actual consumer of the API, I felt that I could ask better questions about the code samples that were provided, and then write better descriptions of them.
Not everyone initially understood that providing the writer with the ability to consume the API would lead to better documentation. After all, the consumers of the API are developers, so the writer only needed to add the code samples to the documentation and provide descriptions. I sometimes found these assumptions slowly eroding the confidence that I had in my role, because I really didn’t have the same level of technical expertise as our developer community.
However, I continued to develop my knowledge of the programming language used for our API, and the integrated development environment (IDE) used by our developers. I eventually obtained a development environment where I could use the API as well as help set it up so that I could run code samples. While I still spend more time reading the code samples sent to me than playing with them, I do have the tools that I need and I’m looking forward to writing some of my own code samples. Perseverance really does pay off.
Learn About Class Libraries
My experience with the API class libraries posed similar challenges to those that I faced when trying to consume the API. Developers use class libraries as a primary source of reference information about the classes, methods, and other features of an API. To create these libraries, developers and API writers add tagged comments to source code describing how to use the API, and then they pull these comments from the source by running automated tools over it.
I had used class libraries as a student in my Java classes, but I had never given much thought to the logistics of writing them, so I was only marginally familiar with the tools used for this purpose. Consequently, I was unable to provide much insight about how API writers collaborated with developers to add comments to the source, or about differences in tools available for this process. Since we were just beginning to create the class libraries, this knowledge would have been invaluable.
I recommend learning as much as you can about the content and organization of class libraries, as well as the tools used to generate them. I would suggest browsing through class libraries to observe the conventions that other writers use in their comments. Since some organizations only reluctantly allow API writers to comment on the source code, I have found that becoming familiar with the processes and tools used to create class libraries has fostered confidence in my abilities to contribute to this development effort.
Understand Your Stakeholder and Users
My role as an API writer had its genesis in the corporate goals set for the adoption of the API. I found that understanding these goals and their stakeholders has helped me adapt the documentation to meet the needs of my readers. Initially, the documentation was designed to educate external third-party developers about the API, but it also evolved into training material used for on-boarding new developers.
I have collaborated with product managers, instructional designers, and other stakeholders to learn about the community of users for this content. In addition, our documentation team has gained insights about the usability of our API documentation by gathering comments from on-boarding developers. We have asked them for feedback and invited them to participate in simple usability testing, so that we could gather insights about missing content, navigational issues, and others enhancements to improve the user experience.
Survey the API Scene
Everyone has an opinion about what makes a good API website. I have checked out websites for other APIs to compare different approaches to documenting this content. I have talked to our developers about API documentation that they found useful, including what they liked about it, and how they would improve it. I have gleaned useful information about different ways that developers consume our content from these discussions.
I have also found that not all developers learn the same way. Some like to start by reviewing the code samples, while others might look over conceptual information or diagrams. In the end, while I found some great ideas by reviewing different API sites, I concluded that the best approach to documenting the API is what made sense for my organization and readers. I also found that we have continually needed to evolve our site as the size and adoption of our API has grown, since we now have readers with even more varied skill sets and expectations about the information that we provide.
Trust Your Gut
One of the most important lessons that I have learned is to trust my own instincts as a technical writer. I currently rely on my development teams to provide code samples included in our developer’s website. Occasionally, I come across a code sample or sample application that doesn’t seem exactly right. It may not exemplify our best practices or it may be confusing to read. Clear code samples offer a great opportunity to demonstrate how third-party developers can effectively use the API.
I have reviewed code samples that would be helpful for an advanced user but may overwhelm a new developer just learning the API. Not all code samples are good teaching tools, so I have worked on providing my development teams with suggestions or standards for the code samples added to the documentation. My recommendation for these situations is to trust your gut by following up with the development team when you think a code sample doesn’t work. While my technical persona has sometimes been intimidated by questioning the code samples, my writer persona has spurred me on in the search for clarity.
Cultivate Your Writing and Technical Skills
Since transitioning as an API writer, I have had the opportunity to interview other candidates for this position. Some candidates tend to emphasize their technical knowledge over their writing skills. The best candidates have paired strong writing skills with their technical knowledge, and they have demonstrated these abilities with samples in their writing portfolios.
In my role as an API writer, I have been required to write a wide range of content in addition to short comments found in class libraries. I have continued to cultivate my writing skills even as I work to expand my technical knowledge. This versatility has come in handy when I needed to create a high-level presentation about the API, standards for code comments, or use cases for specific features.
In addition, I have tried to stay current with new technologies that my organization may want to use in the future. I regret that I don’t always have enough time to research and learn about new technologies, and I continually struggle with finding time for improving my skill sets.
When I first started working on the API, I would sometimes worry about how my technical background might hinder my ability to produce good documentation. I have learned that while I continually need to sharpen my technical skills, I shouldn’t minimize the importance of the communication skills that I bring to this role. API writing offers a unique opportunity to balance technical knowledge with strong communication skills.
Mary Linderman (linderman.mary@gmail.com) is a technical writer at kCura Corporation in Chicago, IL. With over 10 years of technical writing experience, she explores new ways to communicate complex information to readers with a range of technical expertise. Mary’s current interests focus on how corporations can leverage the strategic role that documentation plays in the adoption of APIs by third-party developers.
References
Gruenbaum, Peter. A Coder’s Guide to Writing API Documentation, http://msdn.microsoft.com/en-us/magazine/gg309172.aspx.
Jacobson, Daniel, Greg Brail, and Dan Woods. APIs: Strategy Guide, O’Reilly Media, 2011.
Krug, Steve. Rocket Surgery Made Easy, New Riders, 2009.
Marshall, Ed. APIs and SDKs: Breaking into a Specialty Market, http://tagungen.tekom.de/fileadmin/tx_doccon/slides/267_APIs_and_SDKs_Breaking_Into_and_Succeeding_in_a_Specialty_Market.pdf.
