Recent docs (and tech comm) items of interest.

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).

I didn't discover this feature until today. This should be the default at every presentation! https://t.co/rFlafC5pGl

— Ed H. Chi (@edchi) February 4, 2020

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):

Docs teams are often left to do all of this themselves. People think that the job of a tech writer is non-technical, but that’s not true. Tech writers are often engineering their own tooling solutions and sites with minimal or no help from anywhere in the organization.

— Jenn Leaver (@jennleaver) February 1, 2020

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):

THIS THREAD x1000.

If your company cares about docs, you put engineering (and design and product) effort into making the docs awesome. You put management effort into supporting contributions to docs by encouraging them from your directs.

Great docs are a community effort. https://t.co/C0VoFmqX3q

— Sarah Day (@scribblingfox) February 1, 2020

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:

• They use Hugo, a popular static site generator, for their docs.
• Recently they have published a nice semi-annualish docs roundup of their own.
• The source code for their docs is available on GitHub.
• The Write for Linode program recruits freelance technical writers for original guides and updates.

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?

If 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. 

From 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.

Miscellany

• Twitter poll of interest from Bolaji Ayodeji: How usable is the documentation of your open source project?
• Check out this Swift project docs generator (thank you to Mattt for surfacing the link). Also of Swift interest: NSHipster, “a journal of the overlooked bits in Objective-C, Swift, and Cocoa.”
• The Go programming language (golang) team at Google is looking for a technical writer (and it looks like there is a lot happening with the golang project documentation).
• Curious how we were writing about (and marketing) tech 20 years ago? This post from Rachel Stephens is for you.

Worth 1000 words (design edition)

I gripe a lot about bad design on here, and sometimes give examples of Bad, but for once, I can show you

literally the best design I have ever seen pic.twitter.com/1SD59k8lDw

— Megan Fox (@glassbottommeg) February 3, 2020

 

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.