The Role of Technical Writer in API Documentation
Until recently, technical writers focused on delivering manuals for software, often in PDF or HTML format. These manuals consisted of step-by-step guidance for using software, often accompanied by annotated screenshots. The technical writer was critical for ensuring end users were able to use the software effectively and efficiently while reducing the vendor’s support costs.
With the growth of APIs, technical writers are in heavy demand once again. In this article, we will explore the new role of technical writers, the skills they need to participate in writing API documentation, and the challenges they may encounter as they collaborate with development teams.
Why technical writers are critical for APIs
Technical writers are an invaluable part of an API delivery team. They bring a fresh perspective as they look for ways to turn the technical details of an API into clear documentation for developers. Because they often take a user-centric approach to documentation, they help to focus the API documentation on the needs and questions of the API consumer. This can reduce the learning curve and support a positive developer experience.
Their value doesn’t stop with writing documentation. When given the opportunity, technical writers can turn customer support engagements and developer feedback into recommendations for improvements. This may include documentation improvements, but it may also include design improvements that can benefit current and future API consumers.
I’ve personally experienced tremendous value by involving technical writers early in the API design process. Because they are always evaluating how a specific API operation will be documented, they shed light on API design elements that may be confusing. Questions around the purpose and intended use of each API operation and the API as a whole can help to improve the API design.
Essential API skills for technical writers
For technical writers who have a software developer background, the transition to API documentation is seamless. However, technical writers who have been more product or user-focused may find themselves quickly learning the essentials of APIs. This may include learning how HTTP works, how to leverage YAML and the OpenAPI Specification to capture API reference details, and how to author with asciidoc or markdown rather than XML-based authoring tools such as oXygen.
Technical writers also benefit from learning how to use API client tools, such as Postman, Insomnia, and Hoppscotch. Command-line tools such as cURL may also be useful but aren’t always necessary as it depends on the preferences of the intended audience that will use the API.
They also benefit from learning source control systems such as git or platforms such as GitHub and GitLab to better manage their artifacts and integrate with continuous integration pipelines. Understanding workflows around these systems is also important, including branching and forking documentation for upcoming releases without negatively impacting existing documentation.
In some cases, it can be beneficial for technical writers to learn one or more of the following languages: Java, Python, GoLang, Ruby, JavaScript, Objective-C, Swift, and PHP. However, this isn’t necessary as development teams can help compose examples in these languages to be included in API documentation.
Challenges that technical writers face
Technical writers face a number of challenges as they shift into an API-centric environment. The most common challenge is being able to engage with teams early and often. Most development teams focus on the code rather than documentation, so they don’t consider the involvement of technical writers until late in the development process. By this point, it can be difficult or impossible to make any design changes surface during the documentation effort.
Another challenge is the increased speed of delivery. Today’s delivery processes encourage frequent releases that are measured in days or weeks rather than months. This puts tremendous pressure on technical writers to produce what may be considerable documentation in a short amount of time.
A single technical writer for a small API may be able to keep documentation updated. If the organization is large and manages multiple APIs, the challenge increases beyond the capabilities of even the most talented technical writer. Larger organizations require multiple technical writers of varying levels of expertise to support larger portfolios of APIs.
Many of these challenges can be overcome by ensuring that technical writers are involved earlier in the design and delivery process. They should be considered first-class team members rather than a siloed team that has APIs thrown at them at the last minute for a quick-and-dirty documentation effort.
Conclusion
As APIs become more prevalent, the demand for skilled technical writers who can bridge the gap between complex technical information and the end-user's understanding grows. Their ability to provide clear, concise, and user-centric documentation is essential for facilitating effective developer experiences and enhancing API usability. Finally, remember that API documentation is the user interface for developers. Therefore, technical writers are instrumental in the success of any API.
