![\"Illustration](\"http:\/\/redmonk.com\/kfitzpatrick\/files\/2020\/01\/Escribano.jpg\")
<\/p>\nRecent docs (and tech comm) items of interest.<\/i><\/p>\n
<\/p>\n
Paul Ford, in this gift of a Tweet<\/a> from last week, asked:<\/p>\n What is the best API documentation on the Internet? Everyone stays Stripe. What else?<\/p>\n Along with additional details on why folks love perennial docs darling Stripe<\/a>, multiple respondents also listed Twilio<\/a> (which, along with Stripe, frequently ends up in conversations around great documentation models), and Airtable.<\/p>\n 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:<\/p>\n https:\/\/twitter.com\/PastryPlate\/status\/1219984580112982017<\/p>\n Notably, one of the reasons I find Stripe\u2019s and Twilio\u2019s 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<\/a> 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.<\/p>\n Looking into API doc best practices led me to Tom Johnson<\/a>\u2019s tech writing blog I\u2019d Rather Be Writing<\/a>. 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<\/a>). However, Johnson (currently at Amazon) has also compiled resources from past API docs workshops into an online course on Documenting APIs<\/a>. 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.<\/p>\n 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.<\/p>\n A recent briefing with Adobe<\/a> on their Document Cloud SDKs<\/a> 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<\/a> (and a few additional key PDF workflows<\/a> available via early access), I will be watching to see how this offering develops.<\/p>\n 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.<\/p>\n While folks often see the value in such internal forms of technical communication (even in circumstances where it is unclear<\/a> who should be putting together these resources), it is important to note that technical communication can serve other important functions within a given organization:<\/p>\n 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<\/a> https:\/\/t.co\/olcuXl2CDH<\/a> h\/t to @annashipman<\/a> for sharing.<\/p>\n — Dave Rogers (@daverog) January 22, 2020<\/a><\/p><\/blockquote>\nNod to a tech writing blog<\/h1>\n
PDFs in the era of APIs<\/h1>\n
Internal tech comm<\/h1>\n
\n