Sometimes Dragons

Docs Roundup 1.1

Share via Twitter Share via Facebook Share via Linkedin Share via Reddit

Recent docs (and tech comm) items of interest.

Illustration of 15th-century Burgundian scribe Jean Miélot writing at his desk. He is surrounded by a variety of manuscripts and writing implements.

ICYMI: Automatic captioning in Google Slides  

Whatever else you may think of social media, this week it did us all a favor by surfacing this blog post (from 2018!) on using the closed captions feature when presenting in Google Slides. Captioning is not only an accessibility issue, it also provides your entire audience with an alternative means of digesting spoken words (and I for one am much better at processing content that I can read as well as hear).

On docs teams and engineers

Earlier this week Jenn Leaver (Senior Manager of Product Documentation at GitHub) posted this excellent thread on the relationship between documentation teams and engineers. While documentation teams at software companies often rely on developers and engineers as subject matter experts (SMEs) when creating documentation, Leaver’s narrative addresses the role engineers played in improving the tooling and processes GitHub uses to create and publish documentation. Leaver also surfaces the fact that in many cases technical communicators are left to their own devices when configuring and maintaining their docs setup (which can be especially tricky when taking a docs as code approach):

The bottom line: while great docs might seem like magic, they are usually the work of collaborative and dedicated efforts among different parts of an organization (but good docs are worth the investment):

Docs as code at Linode

Linode, in keeping with their current branding as “Independent open cloud for developers,” recently posted a detailed writeup of their docs as code philosophy and implementation. (Relevant to the GitHub narrative above, one of the stated benefits of this approach: “Working with these technologies helps form a tighter bond between the technical writing team and Linode’s development and engineering teams.”)

Additional notes on Linode’s documentation practices:

Write the Docs

If you are looking for a welcoming and useful docs/tech comm community (or an excellent collection of resources), check out Write the Docs. If conferences are your thing, tickets are still available for their Portland event in May. If travel is not in your cards, they also organize local meetups and host a slack community. 

I can has books?

Cover of Because Internet: Understanding the New Rules of Language, by Gretchen McCullochIf you have not done so already, make time to read Gretchen McCulloch’s book Because Internet: Understanding the New Rules of Language (2019). Described on McCulloch’s website as “A linguistically informed look at how our digital world is transforming the English language,” to my mind the entire book would be worth reading for this single statement alone: “Writing is a technology” (19). As a professional linguist, McCulloch provides clear and thorough analysis of the evolution of the ways we communicate online, and weaves an especially engaging narrative around how technologists helped shape not only the tools and usage patterns of emergent online culture, but also the linguistic and cultural conventions. There is also an entire chapter on memes

Cover of Key Theoretical Frameworks Teaching Technical Communication in the Twenty-First Century edited by Angela M. Haas and Michelle F. EbleFrom the academic side of tech comm, Michelle F. Eble and Angela Haas recently announced that their book, Key Theoretical Frameworks: Teaching Technical Communication in the Twenty-First Century (2018) won the National Council of Teachers of English (NCTE) Conference on College Composition and Communication (CCCC) award for best edited collection on technical communication. Although the volume is explicitly pedagogical, the essays look at technical communication from a range of perspectives including those based in environmental, queer, feminist, and critical race theory: all excellent food for thought for any tech comm practitioner.


Worth 1000 words (design edition)


Have a recent/upcoming docs item you want me to know about? Drop me a line or find me on Twitter.

Disclosure: GitHub is a RedMonk client. 

Image information: Wikimedia Commons; image is in the public domain.

No Comments

Leave a Reply

Your email address will not be published. Required fields are marked *