{"id":161,"date":"2020-02-07T09:26:03","date_gmt":"2020-02-07T17:26:03","guid":{"rendered":"http:\/\/redmonk.com\/kfitzpatrick\/?p=161"},"modified":"2020-02-07T16:57:24","modified_gmt":"2020-02-08T00:57:24","slug":"docs-roundup-1-1","status":"publish","type":"post","link":"https:\/\/redmonk.com\/kfitzpatrick\/2020\/02\/07\/docs-roundup-1-1\/","title":{"rendered":"Docs Roundup 1.1"},"content":{"rendered":"<p><i><span style=\"font-weight: 400;\">Recent docs (and tech comm) items of interest.<\/span><\/i><\/p>\n<p><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter size-full wp-image-159\" src=\"http:\/\/redmonk.com\/kfitzpatrick\/files\/2020\/01\/Escribano.jpg\" alt=\"Illustration of 15th-century Burgundian scribe Jean Mi\u00e9lot writing at his desk. He is surrounded by a variety of manuscripts and writing implements.\" width=\"600\" height=\"464\" srcset=\"https:\/\/redmonk.com\/kfitzpatrick\/files\/2020\/01\/Escribano.jpg 600w, https:\/\/redmonk.com\/kfitzpatrick\/files\/2020\/01\/Escribano-300x232.jpg 300w, https:\/\/redmonk.com\/kfitzpatrick\/files\/2020\/01\/Escribano-480x371.jpg 480w\" sizes=\"auto, (max-width: 600px) 100vw, 600px\" \/><\/p>\n<h1><span style=\"font-weight: 400;\">ICYMI: Automatic captioning in Google Slides\u00a0\u00a0<\/span><\/h1>\n<p><span style=\"font-weight: 400;\">Whatever else you may think of social media, this week it did us all a favor by surfacing this <\/span><a href=\"https:\/\/blog.google\/outreach-initiatives\/accessibility\/whats-you-say-present-captions-google-slides\/amp\"><span style=\"font-weight: 400;\">blog post (from 2018!) on using the closed captions feature when presenting in Google Slides<\/span><\/a><span style=\"font-weight: 400;\">. 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).<\/span><\/p>\n<blockquote class=\"twitter-tweet\" data-width=\"500\" data-dnt=\"true\">\n<p lang=\"en\" dir=\"ltr\">I didn&#39;t discover this feature until today. This should be the default at every presentation! <a href=\"https:\/\/t.co\/rFlafC5pGl\">https:\/\/t.co\/rFlafC5pGl<\/a><\/p>\n<p>&mdash; Ed H. Chi (@edchi) <a href=\"https:\/\/twitter.com\/edchi\/status\/1224561613736415232?ref_src=twsrc%5Etfw\">February 4, 2020<\/a><\/p><\/blockquote>\n<p><script async src=\"https:\/\/platform.twitter.com\/widgets.js\" charset=\"utf-8\"><\/script><\/p>\n<h1><span style=\"font-weight: 400;\">On docs teams and engineers<\/span><\/h1>\n<p><span style=\"font-weight: 400;\">Earlier this week Jenn Leaver (Senior Manager of Product Documentation at <\/span><a href=\"https:\/\/github.com\/\"><span style=\"font-weight: 400;\">GitHub<\/span><\/a><span style=\"font-weight: 400;\">) posted <\/span><a href=\"https:\/\/twitter.com\/jennleaver\/status\/1223660880090619904\"><span style=\"font-weight: 400;\">this excellent thread on the relationship between documentation teams and engineers<\/span><\/a><span style=\"font-weight: 400;\">. While documentation teams at software companies often rely on developers and engineers as subject matter experts (SMEs) when creating documentation, Leaver\u2019s 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 <\/span><a href=\"https:\/\/www.writethedocs.org\/guide\/docs-as-code\/\"><span style=\"font-weight: 400;\">docs as code<\/span><\/a><span style=\"font-weight: 400;\"> approach):<\/span><\/p>\n<blockquote class=\"twitter-tweet\" data-width=\"500\" data-dnt=\"true\">\n<p lang=\"en\" dir=\"ltr\">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\u2019s not true. Tech writers are often engineering their own tooling solutions and sites with minimal or no help from anywhere in the organization.<\/p>\n<p>&mdash; Jenn Leaver (@jennleaver) <a href=\"https:\/\/twitter.com\/jennleaver\/status\/1223660882770743298?ref_src=twsrc%5Etfw\">February 1, 2020<\/a><\/p><\/blockquote>\n<p><script async src=\"https:\/\/platform.twitter.com\/widgets.js\" charset=\"utf-8\"><\/script><\/p>\n<p><span style=\"font-weight: 400;\">The bottom line: while great docs might <\/span><i><span style=\"font-weight: 400;\">seem <\/span><\/i><span style=\"font-weight: 400;\">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):<\/span><\/p>\n<blockquote class=\"twitter-tweet\" data-width=\"500\" data-dnt=\"true\">\n<p lang=\"en\" dir=\"ltr\">THIS THREAD x1000.<\/p>\n<p>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.<\/p>\n<p>Great docs are a community effort. <a href=\"https:\/\/t.co\/C0VoFmqX3q\">https:\/\/t.co\/C0VoFmqX3q<\/a><\/p>\n<p>&mdash; Sarah Day (@scribblingfox) <a href=\"https:\/\/twitter.com\/scribblingfox\/status\/1223686811362328576?ref_src=twsrc%5Etfw\">February 1, 2020<\/a><\/p><\/blockquote>\n<p><script async src=\"https:\/\/platform.twitter.com\/widgets.js\" charset=\"utf-8\"><\/script><\/p>\n<h1><span style=\"font-weight: 400;\">Docs as code at Linode<\/span><\/h1>\n<p><a href=\"https:\/\/www.linode.com\/\"><span style=\"font-weight: 400;\">Linode<\/span><\/a><span style=\"font-weight: 400;\">, in keeping with their current branding as \u201cIndependent open cloud for developers,\u201d recently posted <\/span><a href=\"https:\/\/www.linode.com\/2020\/01\/17\/docs-as-code-at-linode\/\"><span style=\"font-weight: 400;\">a detailed writeup of their docs as code philosophy and implementation<\/span><\/a><span style=\"font-weight: 400;\">. (Relevant to the GitHub narrative above, one of the stated benefits of this approach: \u201cWorking with these technologies helps form a tighter bond between the technical writing team and Linode\u2019s development and engineering teams.\u201d)<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Additional notes on Linode\u2019s documentation practices:<\/span><\/p>\n<ul>\n<li><span style=\"font-weight: 400;\">They use <\/span><a href=\"https:\/\/gohugo.io\/\"><span style=\"font-weight: 400;\">Hugo<\/span><\/a><span style=\"font-weight: 400;\">, a popular static site generator, for their docs.<\/span><\/li>\n<li><span style=\"font-weight: 400;\">Recently they have published a nice <\/span><a href=\"https:\/\/www.linode.com\/2019\/10\/22\/october-docs-roundup-rancher-data-visualization-and-more\/\"><span style=\"font-weight: 400;\">semi-annualish docs roundup of their own<\/span><\/a><span style=\"font-weight: 400;\">.<\/span><\/li>\n<li><span style=\"font-weight: 400;\">The source code for their docs is <\/span><a href=\"https:\/\/github.com\/linode\/docs\"><span style=\"font-weight: 400;\">available on GitHub<\/span><\/a><span style=\"font-weight: 400;\">.<\/span><\/li>\n<li><span style=\"font-weight: 400;\">The <\/span><a href=\"https:\/\/www.linode.com\/lp\/write-for-linode\/\"><span style=\"font-weight: 400;\">Write for Linode<\/span><\/a><span style=\"font-weight: 400;\"> program recruits freelance technical writers for original guides and updates.<\/span><\/li>\n<\/ul>\n<h1><span style=\"font-weight: 400;\">Write the Docs<\/span><\/h1>\n<p><span style=\"font-weight: 400;\">If you are looking for a welcoming and useful docs\/tech comm community (or an excellent collection of resources), check out <\/span><a href=\"https:\/\/www.writethedocs.org\/\"><span style=\"font-weight: 400;\">Write the Docs<\/span><\/a><span style=\"font-weight: 400;\">. If <\/span><a href=\"https:\/\/www.writethedocs.org\/conf\/\"><span style=\"font-weight: 400;\">conferences<\/span><\/a><span style=\"font-weight: 400;\"> are your thing, tickets are still available for their <\/span><a href=\"https:\/\/www.writethedocs.org\/conf\/portland\/2020\/\"><span style=\"font-weight: 400;\">Portland event in May<\/span><\/a><span style=\"font-weight: 400;\">. If travel is not in your cards, they also organize local meetups and host a slack community.\u00a0<\/span><\/p>\n<h1><span style=\"font-weight: 400;\">I can has books?<\/span><\/h1>\n<p><span style=\"font-weight: 400;\"><a href=\"https:\/\/gretchenmcculloch.com\/book\/\"><img loading=\"lazy\" decoding=\"async\" class=\"size-medium wp-image-162 alignleft\" src=\"http:\/\/redmonk.com\/kfitzpatrick\/files\/2020\/02\/McCulloch_cover-199x300.jpg\" alt=\"Cover of Because Internet: Understanding the New Rules of Language, by Gretchen McCulloch\" width=\"199\" height=\"300\" srcset=\"https:\/\/redmonk.com\/kfitzpatrick\/files\/2020\/02\/McCulloch_cover-199x300.jpg 199w, https:\/\/redmonk.com\/kfitzpatrick\/files\/2020\/02\/McCulloch_cover-678x1024.jpg 678w, https:\/\/redmonk.com\/kfitzpatrick\/files\/2020\/02\/McCulloch_cover-768x1160.jpg 768w, https:\/\/redmonk.com\/kfitzpatrick\/files\/2020\/02\/McCulloch_cover-1017x1536.jpg 1017w, https:\/\/redmonk.com\/kfitzpatrick\/files\/2020\/02\/McCulloch_cover-1356x2048.jpg 1356w, https:\/\/redmonk.com\/kfitzpatrick\/files\/2020\/02\/McCulloch_cover-1536x2319.jpg 1536w, https:\/\/redmonk.com\/kfitzpatrick\/files\/2020\/02\/McCulloch_cover-480x725.jpg 480w, https:\/\/redmonk.com\/kfitzpatrick\/files\/2020\/02\/McCulloch_cover-415x627.jpg 415w, https:\/\/redmonk.com\/kfitzpatrick\/files\/2020\/02\/McCulloch_cover-scaled.jpg 1696w\" sizes=\"auto, (max-width: 199px) 100vw, 199px\" \/><\/a>If you have not done so already, make time to read <\/span><a href=\"https:\/\/twitter.com\/GretchenAMcC\"><span style=\"font-weight: 400;\">Gretchen McCulloch<\/span><\/a><span style=\"font-weight: 400;\">\u2019s book <\/span><a href=\"https:\/\/www.penguinrandomhouse.com\/books\/540664\/because-internet-by-gretchen-mcculloch\/9780525626169\/\"><i><span style=\"font-weight: 400;\">Because Internet: Understanding the New Rules of Language<\/span><\/i><\/a> <span style=\"font-weight: 400;\">(2019)<\/span><i><span style=\"font-weight: 400;\">.<\/span><\/i><span style=\"font-weight: 400;\"> Described <\/span><a href=\"https:\/\/gretchenmcculloch.com\/book\/\"><span style=\"font-weight: 400;\">on McCulloch\u2019s website<\/span><\/a><span style=\"font-weight: 400;\"> as \u201cA linguistically informed look at how our digital world is transforming the English language,\u201d to my mind the entire book would be worth reading for this single statement alone: \u201cWriting is a technology\u201d (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 <\/span><a href=\"https:\/\/cheezburger.com\/875511040\/original-cat-meme-that-started-cheezburger\"><span style=\"font-weight: 400;\">memes<\/span><\/a><span style=\"font-weight: 400;\">.\u00a0<\/span><\/p>\n<p><span style=\"font-weight: 400;\"><a href=\"https:\/\/upcolorado.com\/utah-state-university-press\/item\/3425-key-theoretical-frameworks\"><img loading=\"lazy\" decoding=\"async\" class=\"size-full wp-image-163 alignright\" src=\"http:\/\/redmonk.com\/kfitzpatrick\/files\/2020\/02\/Key_Theoretical_Frameworks_cover.jpg\" alt=\"Cover of Key Theoretical Frameworks Teaching Technical Communication in the Twenty-First Century edited by Angela M. Haas and Michelle F. Eble\" width=\"200\" height=\"282\" \/><\/a>From the academic side of tech comm, <\/span><a href=\"https:\/\/twitter.com\/meble\"><span style=\"font-weight: 400;\">Michelle F. Eble<\/span><\/a><span style=\"font-weight: 400;\"> and <\/span><a href=\"https:\/\/twitter.com\/angela_haas\"><span style=\"font-weight: 400;\">Angela Haas<\/span><\/a><span style=\"font-weight: 400;\"> recently <a href=\"https:\/\/twitter.com\/meble\/status\/1225562444120104961\">announced<\/a> that their book, <\/span><a href=\"https:\/\/upcolorado.com\/utah-state-university-press\/item\/3425-key-theoretical-frameworks\"><span style=\"font-weight: 400;\">Key Theoretical Frameworks: Teaching Technical Communication in the Twenty-First Century<\/span><\/a><span style=\"font-weight: 400;\"> (2018) won the National Council of Teachers of English (<\/span><span style=\"font-weight: 400;\">NCTE<\/span><span style=\"font-weight: 400;\">) Conference on College Composition and Communication (<\/span><span style=\"font-weight: 400;\">CCCC<\/span><span style=\"font-weight: 400;\">) award for <\/span><a href=\"https:\/\/cccc.ncte.org\/cccc\/awards\/techsci\"><span style=\"font-weight: 400;\">best edited collection on technical communication<\/span><\/a><span style=\"font-weight: 400;\">. 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.<\/span><\/p>\n<h1><span style=\"font-weight: 400;\">Miscellany<\/span><\/h1>\n<ul>\n<li style=\"font-weight: 400;\"><span style=\"font-weight: 400;\">Twitter poll of interest from Bolaji Ayodeji: <\/span><a href=\"https:\/\/twitter.com\/iambolajiayo\/status\/1225476728279257088\"><span style=\"font-weight: 400;\">How usable is the documentation of your open source project<\/span><\/a><span style=\"font-weight: 400;\">?<\/span><\/li>\n<li style=\"font-weight: 400;\"><span style=\"font-weight: 400;\">Check out this <\/span><a href=\"https:\/\/github.com\/SwiftDocOrg\/swift-doc\"><span style=\"font-weight: 400;\">Swift project docs generator<\/span><\/a><span style=\"font-weight: 400;\"> (thank you to <\/span><a href=\"https:\/\/twitter.com\/mattt\/status\/1221863163915694085\"><span style=\"font-weight: 400;\">Mattt for surfacing the link<\/span><\/a><span style=\"font-weight: 400;\">). Also of Swift interest: <\/span><a href=\"https:\/\/nshipster.com\/\"><span style=\"font-weight: 400;\">NSHipster<\/span><\/a><span style=\"font-weight: 400;\">, \u201ca journal of the overlooked bits in Objective-C, Swift, and Cocoa.\u201d<\/span><\/li>\n<li style=\"font-weight: 400;\"><span style=\"font-weight: 400;\">The <\/span><a href=\"https:\/\/golang.org\/\"><span style=\"font-weight: 400;\">Go programming language<\/span><\/a><span style=\"font-weight: 400;\"> (golang) team at Google is <\/span><a href=\"https:\/\/twitter.com\/Sajma\/status\/1222706825897922561\"><span style=\"font-weight: 400;\">looking for a technical writer<\/span><\/a><span style=\"font-weight: 400;\"> (and it looks like there is <\/span><a href=\"https:\/\/blog.golang.org\/pkg.go.dev-2020\"><span style=\"font-weight: 400;\">a lot happening with the golang project documentation<\/span><\/a><span style=\"font-weight: 400;\">).<\/span><\/li>\n<li style=\"font-weight: 400;\"><span style=\"font-weight: 400;\">Curious how we were writing about (and marketing) tech 20 years ago? <\/span><a href=\"https:\/\/redmonk.com\/rstephens\/2020\/02\/07\/wired-2000-01\/\"><span style=\"font-weight: 400;\">This post from Rachel Stephens<\/span><\/a><span style=\"font-weight: 400;\"> is for you.<\/span><\/li>\n<\/ul>\n<h1><span style=\"font-weight: 400;\">Worth 1000 words (design edition)<\/span><\/h1>\n<blockquote class=\"twitter-tweet\" data-width=\"500\" data-dnt=\"true\">\n<p lang=\"en\" dir=\"ltr\">I gripe a lot about bad design on here, and sometimes give examples of Bad, but for once, I can show you<\/p>\n<p>literally the best design I have ever seen <a href=\"https:\/\/t.co\/1SD59k8lDw\">pic.twitter.com\/1SD59k8lDw<\/a><\/p>\n<p>&mdash; Megan Fox (@glassbottommeg) <a href=\"https:\/\/twitter.com\/glassbottommeg\/status\/1224391322934464515?ref_src=twsrc%5Etfw\">February 3, 2020<\/a><\/p><\/blockquote>\n<p><script async src=\"https:\/\/platform.twitter.com\/widgets.js\" charset=\"utf-8\"><\/script><\/p>\n<p>&nbsp;<\/p>\n<p><b>Have a recent\/upcoming docs item you want me to know about? <\/b><a href=\"mailto:kellyann@redmonk.com\"><span style=\"font-weight: 400;\">Drop me a line<\/span><\/a><span style=\"font-weight: 400;\"> or <\/span><a href=\"https:\/\/twitter.com\/drkellyannfitz\"><span style=\"font-weight: 400;\">find me on Twitter<\/span><\/a><span style=\"font-weight: 400;\">.<\/span><\/p>\n<p><b>Disclosure<\/b><span style=\"font-weight: 400;\">: GitHub is a RedMonk client.\u00a0<\/span><\/p>\n<p><b>Image information:<\/b> <a href=\"https:\/\/commons.wikimedia.org\/wiki\/File:Escribano.jpg\"><span style=\"font-weight: 400;\">Wikimedia Commons<\/span><\/a><span style=\"font-weight: 400;\">; image is in the public domain.<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Recent docs (and tech comm) items of interest. ICYMI: Automatic captioning in Google Slides\u00a0\u00a0 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,<\/p>\n","protected":false},"author":47,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"spay_email":"","footnotes":"","jetpack_publicize_message":"","jetpack_is_tweetstorm":false},"categories":[30,4],"tags":[],"class_list":["post-161","post","type-post","status-publish","format-standard","hentry","category-docs-roundup","category-tech-comm"],"jetpack_featured_media_url":"","jetpack_publicize_connections":[],"jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/redmonk.com\/kfitzpatrick\/wp-json\/wp\/v2\/posts\/161","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/redmonk.com\/kfitzpatrick\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/redmonk.com\/kfitzpatrick\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/redmonk.com\/kfitzpatrick\/wp-json\/wp\/v2\/users\/47"}],"replies":[{"embeddable":true,"href":"https:\/\/redmonk.com\/kfitzpatrick\/wp-json\/wp\/v2\/comments?post=161"}],"version-history":[{"count":0,"href":"https:\/\/redmonk.com\/kfitzpatrick\/wp-json\/wp\/v2\/posts\/161\/revisions"}],"wp:attachment":[{"href":"https:\/\/redmonk.com\/kfitzpatrick\/wp-json\/wp\/v2\/media?parent=161"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/redmonk.com\/kfitzpatrick\/wp-json\/wp\/v2\/categories?post=161"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/redmonk.com\/kfitzpatrick\/wp-json\/wp\/v2\/tags?post=161"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}