Recent docs (and tech comm) items of interest.
What makes good API docs?
Paul Ford, in this gift of a Tweet from last week, asked:
What is the best API documentation on the Internet? Everyone stays Stripe. What else?
Along with additional details on why folks love perennial docs darling Stripe, multiple respondents also listed Twilio (which, along with Stripe, frequently ends up in conversations around great documentation models), and Airtable.
While I consider best practices for and favorite developer examples of API docs to be an ongoing area of interest, one comment that stood out for me conveyed understandable frustration at the assumption that a given user should automatically know how to use API docs:
Mapbox is pretty good. But the standard for “best” is still a pretty low bar for API documentation. Mostly, API tech writers assume everyone knows where the front door is. I wrote a LOT of help docs and that did and still does, drives me BATSH*T!
— PastryPlate (@PastryPlate) January 22, 2020
Notably, one of the reasons I find Stripe’s and Twilio’s API docs to be so useful is that a new user approaching them for the first time has the benefit of getting started guides and clear use cases. I also like that I can access the documentation without having to create a login. While I do appreciate that account creation is necessary for generating customized documentation (as Airtable does), I still want to be able to get an idea of how you have structured your APIs (and how well you explain this in your API reference) before I commit to creating yet another login.
Nod to a tech writing blog
Looking into API doc best practices led me to Tom Johnson’s tech writing blog I’d Rather Be Writing. The blog per se is a useful resource for tech writing in general and API documentation in particular (pertinent to the API docs conversation above, I really like this post on When reference docs lack a tutorial). However, Johnson (currently at Amazon) has also compiled resources from past API docs workshops into an online course on Documenting APIs. If you are a developer who has been tasked with documenting APIs or a tech writer looking to hone your skills, this is worth a look.
PDFs in the era of APIs
Earlier this week a default library path issue on a new software installation sent me scurrying for the installation manual, which was packaged as a PDF. For me this was a reminder of the ubiquity of PDFs, even in an era of auto-generated custom API documentation. As much as folks like to hate on PDFs, we use them for contracts, tax documents, a multitude of educational purposes, as a standardized method of sharing presentation slides, and for what is likely a thousand other uses for which PDFs are a superior alternative to paper.
A recent briefing with Adobe on their Document Cloud SDKs further reminded me that with our increased reliance on PDFs comes increased demand for ways to integrate PDF-related functionality into many different types of applications. Generating receipts for an online transaction? You need to create a PDF. Searching for a way for instructors to provide feedback on student assignments in your Learning Management System? You need comment functionality. Sharing sensitive information? You need protection. And so it goes. While the Document Cloud currently has an SDK for integrating view functionality (and a few additional key PDF workflows available via early access), I will be watching to see how this offering develops.
Internal tech comm
Anyone who has ever undergone the onboarding process at a new job can attest to how important internal documentation of processes and information can be. My RedMonk onboarding, for instance, was rendered at least 50 times more efficient by the meticulous spreadsheets, notes, and informal advice that my colleagues had put in place.
While folks often see the value in such internal forms of technical communication (even in circumstances where it is unclear who should be putting together these resources), it is important to note that technical communication can serve other important functions within a given organization:
Organisations need to know the state they're in, and this includes technology. This can only be done with clear, simple and truthful approaches to technical communication. Here's a brilliant example by @pollyrt https://t.co/olcuXl2CDH h/t to @annashipman for sharing.
— Dave Rogers (@daverog) January 22, 2020
Polly Thompson’s The State We’re In post is a great example of how technical communication process can be used to better understand the state of an organization. More importantly, the post emphasizes a user-centric approach (focusing on user needs) to internal tech comm. Because we often don’t think of our coworkers and colleagues as users, to my mind this is an especially useful point of view to start from when creating and updating content designed for internal use.
Docs, safety, signaling (and a novel)
Thomas Otter recently posted this short but excellent piece on Documentation and Safety (with a shout out to our tech comm review offering). Dr. Otter notes that good documentation in software is akin to safety in manufacturing: both become linked to an organization’s brand and both provide potential customers important criteria used to gauge product quality (therein lies the “signaling” part). He also offers up this gem of a sentence: “Documentation is not glamorous, but it is goodness.” It is also worth noting that the post opens with the charge to add Gene Kim’s new novel, The Unicorn Project (2019), to your “Things to be read” list: a charge with which I wholeheartedly agree.
Worth 1000 words
— Peter Hicks (@poggs) January 25, 2020
Have a recent/upcoming docs item that you think I should know about? Drop me a line or find me on Twitter.
Disclosure: Amazon and Adobe are RedMonk clients. Stripe, Twilio, and Airtable currently are not RedMonk clients
Image information: Wikimedia Commons; image is in the public domain.
No Comments