This spotlight article features Brandon David, a software developer and programmer writer with experience in API writing, source documentation, and documentation engineering.
How did you get into API writing?
With a toddler at home and a baby on the way, I was looking for a remote position that offered great flexibility. Despite frequently using developer documentation in my previous work, I wasn’t that aware of API writing as a role, and so it wasn’t part of my job search. By chance, I stumbled onto a job posting that matched the work-life balance I was seeking and soon found myself documenting APIs.
How does being a programmer writer compare to working solely on API documentation?
In general, programmer writers have sufficient programming knowledge to work closely with code without requiring a developer to explain it. People working solely on API documentation typically don’t have the same level of programming knowledge, but that isn’t always the case. For example, some API writers write sample code for highly technical developer tutorials or maintain complex documentation generation pipelines. Many API writers have web development skills due to their work maintaining online developer portals, where API documentation resides alongside developer tutorials and other conceptual information.
What was the most interesting project you’ve worked on?
I was contracted by the Berkeley Institute for Data Science to help with the statistics module of SciPy, a scientific computing library for Python. Most of my time was spent correcting and expanding docstrings, which are comment blocks in code that document a specific function and are typically used to generate developer-facing documentation. My largest project was to standardize docstrings according to a strict style guide and to write validation scripts that helped automate that effort.
I was thankful to have some background in statistics; it was often necessary to consult journal articles and other academic sources to verify a function’s intent, implementation, or documentation. Overall, it was fascinating to be a part of an important open-source project used by millions of people every day.
What advice would you give to individuals who are aspiring to become API writers?
Aspiring API writers should be prepared to learn a tall stack of industry-specific tools and methodologies. Most software documentation today is created through a docs-as-code approach, where software and its documentation are produced with the same tools and platforms. It may be a challenge that these tools are tailored for developers and not writers, but learning them is an excellent way for writers interested in a software career to begin that transition.
What kind of tools are important for API writers to familiarize themselves with?
Most REST APIs today are documented according to OAS3, the current OpenAPI Specification. OAS3 files can be written using a simple text editor, but software such as Postman, Insomnia, or Stoplight Studio can offer features such as team collaboration, mock servers, and support for GraphQL and gRPC. OAS3 files are often parsed and deployed onto developer portals through an SSG (static site generator), such as Sphinx, Hugo, or Antora. API writers should also be familiar with Agile software development practices, such as Scrum, and version control workflows, such as GitHub flow.
Ulysses Aganon is an English and Professional Writing student and an aspiring technical writer. He has worked as a technical writing intern for Ericsson Telecommunications Ltd. and is currently an intern for STC Canada West Coast. He lives in Mississauga, Ontario.