API documentation
- What is API documentation?
- Why I adopted API documentation
- Why I didn’t abandon API documentation
- Current status
- Takeaway
- Next post
What is API documentation?
Application programming interfaces (APIs) have been around even before the Internet, but most APIs were library-based APIs, such as Java or C++ APIs. Around 2010 or so, web APIs (most commonly, REST APIs) started to emerge in a popular way, and APIs began to proliferate among companies.
Web APIs also seemed to change the importance of documentation. Whereas docs for library-based APIs are generated from annotations in the source code through tools like Javadoc and Doxygen (and the outputs from these tools looked more or less the same), with web APIs, documentation isn’t always generated from source annotations. At least half the time, people create reference docs manually. In fact, many API designers advocate using the OpenAPI specification (also called Swagger) to design the API before you even begin coding. The reference docs can be generated from this Open API spec rather than source-code annotations.
Regardless of the reasons why, documentation for REST APIs almost varies dramatically from site to site. Even though you can generate reference docs from the source using tools like Swagger UI, the reference docs are just one part of the larger documentation. There’s a lot more content needed, which I cover in Conceptual topics section of my API course:
- API product overviews
- API getting started tutorials
- API authentication and authorization
- API status and error codes
- API rate limiting and thresholds
- API quick reference
- API glossary
- API best practices
As you can see, there are a lot of opportunities for technical writers to contribute to developer documentation, especially with web APIs. Additionally, companies often dedicate UX resources to create modern-looking, web-friendly sites for their API docs, bringing both reference and non-reference content together in seamless ways.
Why I adopted API documentation
When I moved out to California, it seemed most jobs in the Bay area involved API documentation. Jobs in API documentation tended to pay more, there was a higher demand for them, the work was more challenging, and it was generally an interesting space to be in.
Also, the emergence of web APIs made it easier for non-developers (e.g., tech writers with humanities backgrounds) to get involved in API documentation. Because web APIs are language agnostic, they’re more accessible for tech writers to understand and document. At the core, REST APIs involve a simple request and response, which you can observe using curl or using tools like Postman (rather than building sample Java apps, for example). The response is usually returned in JSON as well, which makes it easy to read. In contrast, if my first API documentation job would have involved documenting a Java API, I might have concluded that I needed to be a developer to write the docs.
Besides the technical aspects of developer documentation, APIs provided a totally new landscape to explore. Writing API docs involved a new type of user (developers), code examples, end-to-end tutorials, getting started guides, API explorers, and more. You could put your hands on code in a low-cost way and make it work, which was fun. I was already somewhat tech savvy (having worked as a WordPress consultant for years, though by no means at a developer level), and I found that I liked working with code and in the developer space.
Also, within the tech comm industry, there had been a growing shift from traditional user documentation to API documentation. Documentation for GUI apps shifted more to the UI, with the emergence of UX writing. Some even said that the tech writer role was dying, no longer needed. If your product requires docs to figure out, it’s dead in the water anyway, regardless of how good the supporting manual is. Users will choose simple, easy-to-understand interfaces over confusing ones that require reading through docs to figure out. As a result, companies often poured more resources into UX design rather than documentation. And the UX discipline matured.
UX maturity created less of a demand for documentation around interface-based solutions. With better UIs, users could more easily learn software through trial and error or interface help text. The demand for docs shifted more in the API space, where users didn’t have a UI to explore and figure out on their own. It’s hard to guess the parameters of an API without some sort of docs. Some years ago, you used to hear the phrase “No one reads the docs” every now and then. It’s not really the case within the developer documentation space. (And the phrase is less common in other spaces as well.)
Why I didn’t abandon API documentation
The shift into API documentation helped me find my niche in tech comm circles. Everyone specializes in some aspect of tech comm. For example, some become UX writers, CCMS experts, DITA consultants, Flare experts, and so on. API documentation seemed to be my specialization, and I embraced it.
Also, financially speaking, once you start working for big tech companies and realize that the salary packages are on another level, it’s not really something you abandon. There’s a continual, growing need for API documentation across big tech, and the search for unicorn tech writers (people who are comfortable in both programming languages and writing) continues to be strong. I feel a lot more stable in this field. It’s challenging, for sure, but this also means there’s always a lot of opportunities for continual learning and advancement.
Current status
About 75% of the traffic to my site goes to my API documentation course — and it’s been that way for several years, ever since I created my API course. I think these analytics speak to the larger trends of API documentation itself. API docs are a high-demand subject area, with rewarding challenges to keep professionals engaged and learning.
In 2015, I wrote a post titled My 2016 technical writing trends and predictions, or the ripple effects of API growth on technical writers. I made a series of predictions based on one ground truth: that APIs were going to create a ripple effect across the tech comm industry. What were the specifics of these ripples? I listed 9 outcomes from the continued growth and popularity of APIs:
- Use of Swagger with API docs becomes an expectation
- Markdown as an authoring format gets taken more seriously by the tech comm community
- Github as a collaboration platform rises in popularity among tech writers
- Write the Docs meetup groups proliferate over STC
- Security paranoia forces authentication of docs
- Tech writers explore non-traditional tools instead of HATs
- Technical writers create more tutorials (instead of just tasks)
- Technical writers study at least one programming language
- Technical writers deliver content via APIs themselves
All of these predictions more or less played out in a true way.
APIs are here to stay. The web created a shift toward the information economy, where a company’s primary product is no longer a physical asset but rather information delivered through APIs. Data is what is bought and sold online. As long as the information economy continues to drive corporate products and services, APIs and related documentation will be in high demand.
Still, it’s challenging to find tech writers who are both experts in documentation and programming languages (and docs-as-code tools, too). Employers are often willing to overlook writing experience in favor of technical knowledge. If you’re young and want to move up in this field, consider going to a technical bootcamp rather than a tech comm program. If you can write reasonably well already, focus more on building up your technical expertise, and doors will open.
Takeaway
The growth of web APIs led to a surge of opportunities for technical writers to work in developer documentation.
Next post
Continue to the next post in this series: GitHub and open-source.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.