Documentation in Developer Practices with Riona Macnamara

Google Cloud Platform Podcast

Episode | Podcast

Date: Wed, 08 Jul 2020 00:00:00 +0000

<p><a href="https://twitter.com/markmirch">Mark Mirchandani</a> and <a href="https://twitter.com/pvergadia">Priyanka Vergadia</a> are here this week to talk about some cool things that are going on. Then, Mark brings us an interesting interview all about documentation in development with Technical Writing Manager <a href="https://twitter.com/rionam">Riona Macnamara</a>. Riona specializes in technical documentation for DevOps at Google.</p> <p>Having written technical documentation for both external and internal audiences, Riona starts the show comparing the two, explaining how the process can be very different. In external writing, she stresses the importance of engineers and technical writers working together. She details the challenges of documentation in code development culture and offers some solutions. Laying out goals can create better quality documents, while providing a simple documentation process for engineers can help bolster a culture of documenting. She talks about open source projects, stressing that documentation is possibly more necessary because of the diverse contributor base.</p> <p>We wrap up the interview learning how to get started creating and maintaining useful documentation. Better trumps best with documentation; a lot of decent documentation is better than very few documents no one can find or use!</p> <h5 id="riona-macnamara">Riona Macnamara</h5> <p>Riona is a 13-year Google veteran, and a documentation manager in Google Cloud. Previously at Google, she drove Google’s open source documentation strategy, led the team that developed Google’s internal engineering doc platform used by more than 20,000 projects, and supported Google’s Webmaster Tools (now Search Console). Before Google, she was a product manager at Amazon, and spent ten years at Microsoft as an editor on Encarta and mapping products, and a technical writer. She is a frequent speaker on documentation, open source, and diversity and inclusion, and is based in New York City.</p> <h5 id="cool-things-of-the-week">Cool things of the week</h5> <ul> <li>Google Cloud VMware Engine is now generally available <a href="https://cloud.google.com/blog/topics/hybrid-cloud/google-cloud-vmware-engine-is-generally-available"> blog</a></li> <li>I built an AI-powered moderation bot for Discord <a href="https://www.youtube.com/watch?v=ABr_HkO0eGk">video</a></li> </ul> <h5 id="interview">Interview</h5> <ul> <li>Berlin Buzzwords 2019: Aizhamal Nurmamat Kyzy & Riona MacNamara - From User to Contributor <a href="https://www.youtube.com/watch?v=wGy25DYarLY&amp;t=663s">video</a></li> <li>Documentation for Good: Knowledge as a tool for equity and inclusion <a href="https://www.youtube.com/watch?v=HBEvHvv3YV4&amp;t=1086s">video</a></li> <li>SREcon18 Asia/Australia - Do Docs Better: Practical Tips on Delivering Value to your Business <a href="https://www.youtube.com/watch?v=17f8elHd6aM&amp;t=149s">video</a></li> <li>DevOps Days Galway <a href="https://www.youtube.com/channel/UCs3qTYCBoVQRDwpBPjBNWFQ">videos</a></li> <li>Write the Docs Portland 2019 <a href="https://www.youtube.com/playlist?list=PLZAeFn6dfHpmuHCu5qsIkmp9H5jFD-xq-"> videos</a></li> <li>Write the Docs Australia 2019 <a href="https://www.youtube.com/playlist?list=PLy70RNJ7dYrJPuUTAIOS7vWGw6poKDHtH"> videos</a></li> <li>Technical Writing Courses at Google <a href="https://developers.google.com/tech-writing">site</a></li> <li>Docs Like Code on Amazon <a href="https://www.amazon.com/gp/product/B0784ZJWSR/ref=dbs_a_def_rwt_hsch_vapi_tkin_p1_i0"> site</a></li> </ul> <h5 id="tip-of-the-week">Tip of the week</h5> <p>This week, we learn <a href="https://www.youtube.com/watch?v=1qG4BabzoXo">how to authenticate a REST API</a>.</p> <h5 id="what-s-something-cool-you-re-working-on">What’s something cool you’re working on?</h5> <p>Riona will be the Keynote speaker for <a href="https://tcworld-india.com/program-2020/program-detail/?tx_news_pi1%5Bnews%5D=99&amp;cHash=0d9bfe570ba25b9ae513189d579f9c32"> TCWorld India</a></p> <p>Priyanka’s been working on new episodes of Cloud Bytes. <a href="https://www.youtube.com/watch?v=Xuf3J6SKVV0">App Engine in a Minute</a> is now up! She’s also working on her series <a href="https://medium.com/google-cloud/gcpcomics/home">GCP Comics</a>.</p>