This is a guest post from Jennifer Rondeau, a Technical Writing Manager at Capital One.
This is a post for beginners. Specifically, it’s a post for technical writers (regardless of specific job title) who want to learn more about API documentation, a realm traditionally separated from other forms of software documentation, and often made mysterious by folks who don’t use it or make it.
That I find this post necessary says quite a lot about the state of software documentation and the technical writers who produce much of it, but that’s a point I’ll explore in more detail another day. For the time being, I want to offer advice that’s meant to complement what other technical writers have said or written on the subject.
Here’s the why of my advice, which is bigger than just API documentation. In case you hadn’t noticed (and it seems that this particular rearguard action is still being fought), the new (or renewed) world of software documentation is moving rapidly toward a world that no longer isolates writers in their own little silos with their own proprietary tools and workflows to which no one else has access. This is particularly true for developer documentation, of which API docs are (partly) a subset. So if you haven’t done it already, you need to start thinking of yourself as part of a product development team, not as part of a documentation team. You are writing with and for products team, and especially for product managers and developers. Which means you need to turn yourself into as much of a PM/dev as you possible can.
So, try shifting focus. Stop reading about “API documentation.” At least for a while. And start reading about APIs. Specifically, read about REST, because that’s what almost everyone means by “API” these days.
(As I write, the one highly visible exception to the mainstream equation of “API” with “REST” is the Oracle v Google case. But the high level issues around what an API is are still the same — they are all interfaces, surfaces that other things can connect to without knowing what’s underneath the surface. And indeed, they should not know.)
Instead, try some of these suggestions:
- Read API and developer blogs, and read up on the major API management platforms. Yes, these are commercial ventures, but the folks who have built them have invested a lot in educating communities about APIs and in providing great information that any aspiring API documentarian should be familiar with. Here are just a few of my favorite resources. This list is not comprehensive — explore on your own and come up with your own set of tabs and bookmarks of similar material.
- The Nordic APIs blog
- Matthew Reinbold’s REST API Notes, his website, and his listing of API events. (Matthew is a colleague and I’m very fortunate to be working with him. Read his stuff, and anything he recommends.)
- James Higginbotham’s site. Also, sign up for API Developer Weekly,the newsletter that he puts out with Keith Casey
- Kin Lane’s API Evangelist site (start with the blog, and then explore further)
- Programmable Web. It’s a lot about the business side of APIs, but you need that, too.
- (Not for the faint of heart) The words that started it all, Roy Fielding’s dissertation (although as Fielding continues to point out, REST is really just how the web works. Or ought to work.)
- (shameless plug) I said not to read me, but I mention a few other good resources (tools, folks to follow on twitter) in this interview with Jennifer Riggins on APIEconomist: http://apieconomist.com/blog/jennifer-rondeau-on-the-mix-of-grammar-and-tech-in-api-documentation.
- Attend local API meetups.
- Learn about OAuth 2.0 (and about the controversies surrounding it). I mean really learn — read the spec, and read a lot of different docs (about different implementations — everybody implements OAuth in their own way, because it’s not a tool, it’s a specification).
- OAuth 2 spec https://tools.ietf.org/html/rfc6749
- Learn about API security — properly speaking about web security more generally. Learn about certificate stores, and encryption. This, with OAuth, is an area that far too few folks pay sufficient attention to, and it badly needs the help of good documentarians who can help developers understand its importance and show them good security solutions.
Remember that the developers who are the audience for API documentation are users, too. Developer Experience (DX) is your new UX. As you learn more about APIs, you’ll learn about good API design, and this is tremendously important. As with any other interface, if you’re having a hard time documenting an API, and the docs are getting complex and convoluted as you chase down tangled details, chances are the API could use a good redesign. Catch these issues, as you would poorly worded GUI text or a badly laid out GUI, and you’ll make life easier for everyone. (You’ll also help evangelize the role of writer as a key member of the product dev team while you’re at it.)
The appearance of external hyperlinks does not constitute endorsement by the ISTC of the linked websites, or the information, products or services contained on those sites. All external hyperlinks were accurate and working at the time of writing. However, the ISTC does not exercise any editorial control over the information you may find at these locations, so the ISTC cannot be responsible for changes to content found at these locations or any material on those sites that may be inaccurate, misleading or offensive to you.
Jennifer is currently a Technical Writing Manager at Capital One, where she documents public-facing APIs and occasionally helps design them. She also helps organise the Write the Docs(WTD) North America conference, and is deeply committed to the community that is emerging around WTD. You can find her on Twitter, @bradamante, and occasionally on her fitfully maintained blog, yourmom.io.