Growing trends for APIs and my favorite resources to learn technical information
While riding home on the train today, I was thinking about directions I want to take my career. I actually don't have any presentations pending, no expected slides or research due (other than an article on gamification).
As I thought about it, I realized that I want to dive more deeply into API documentation. The response to the API Workshop I'm helping organize has been really encouraging. Already we have 45 people signed up (with a cap of 60), and we haven't marketed it much at all.
This interest among technical writers, though, isn't what is driving my attention toward API documentation. Instead, what gets my attention is the constant number of new APIs being added to the Programmable Web's API directory. The directory already contains more than 10,000 APIs. Last week, 56 new APIs were added to the directory.
API documentation examples
Almost all of the APIs on the Programmable Web have documentation. The other day I started collecting links to the documentation. Here are a few:
Undoubtedly, there's a growing trend toward API documentation, with many unanswered questions, such as who writes the API documentation? What tools and methods are they using? What separates good API documentation from bad? Are the writers using structured authoring such as DITA? Are print deliverables involved with API documentation? What are the best methods for organizing API content? How do you integrate code examples with the API reference information? And so on.
Learning programming
Despite my many questions, one thing is clear: You need to understand programming concepts and details in order to work with API documentation.
And where will you get this programming knowledge? You learn many details by reading specs, talking with engineers, and exploring the API on your own. But for the most part, you need a technical library of material to guide you.
In my experience, there's one technical library that stands out above all the rest: Safari Books Online. This massive library has dozens of books on nearly every technical subject.
For example, when I started my job at Badgeville documenting a JavaScript SDK, I read about a dozen different books on JavaScript through Safari. I didn't read every page of each book -- because the beauty of Safari is that you don't have to.
With Safari, you can select an "all you can eat" plan for one price. You read a chapter here and there from a variety of books. Some authors write for novices while others write for experts. Some are articulate while others aren't as clear. When one source fails to explain, there are many more options.
Many of the books from XML Press are in the Safari library, but by and large, it's a library for developer-oriented information. You're not going to find too many books on technical writing in there (besides some XML Press books, there are a few on DITA).
But that's not really a problem. Most technical writers I know don't read books on tech comm because they're already comfortable in their field. What I need are books that teach me programming so that I can better document APIs and SDKs, so that I can understand what the heck engineers are writing. The Safari library couldn't be any more relevant to this task.
Safari Books Online has several subscription options. The unlimited access model costs $42.99 a month. You can also choose a 10-slot bookshelf for $27.99 or a 5-slot bookshelf for $9.99 a month.
Safari has another resource called Safari Flow. Safari Flow is a subset of the regular Safari library and focuses more on web development topics. Safari Flow has a completely responsive interface, so rather than an app that you download for your mobile device, you can actually just log into the site from your mobile device to access the content.
I beta-tested Safari Flow and then transitioned to a regular Flow subscriber.
Of course, I don't have endless money for subscriptions, so when I switched to Safari Flow I sadly ended my regular Safari Books Online subscription. However, I found that I can access Safari Books Online for free through a resource portal from my library's Internet page. I just have to type in my barcode on the web page for the access.
There are a few drawbacks to using the library portal instead of a regular subscription. First, video content is not included in my library's subscription. Second, I can't save books to a favorites list, and the site doesn't remember where I quit reading. Third, I can't access the content via the mobile app, which is where I often read the content.
Finally, I've noticed that when I was an active subscriber paying $42.99 a month, I made sure to use the library more regularly. When it's free, the incentive isn't as strong. But I do use Safari Flow more regularly.
However you get your information, remember that there are a lot of online resources available. Besides the Safari resources I mentioned, a few others include codecademy.com, teamtreehouse.com, khanacademy.org, and many more.
The point is to leverage the available resources to learn the technical details necessary to interact with engineers in documenting APIs. Opportunities for experienced API technical writers are abundant, and the need is only growing. Additionally, API documentation presents a new and challenging landscape to tech comm that is both engaging and interesting.
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.