Documentation in Developer Practices with Riona Macnamara

Mark Mirchandani and Priyanka Vergadia 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 Riona Macnamara. Riona specializes in technical documentation for DevOps at Google.

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.

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!

Riona Macnamara

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.

Cool things of the week

• Google Cloud VMware Engine is now generally available blog
• I built an AI-powered moderation bot for Discord video

Interview

• Berlin Buzzwords 2019: Aizhamal Nurmamat Kyzy & Riona MacNamara - From User to Contributor video
• Documentation for Good: Knowledge as a tool for equity and inclusion video
• SREcon18 Asia/Australia - Do Docs Better: Practical Tips on Delivering Value to your Business video
• DevOps Days Galway videos
• Write the Docs Portland 2019 videos
• Write the Docs Australia 2019 videos
• Technical Writing Courses at Google site
• Docs Like Code on Amazon site

Tip of the week

This week, we learn how to authenticate a REST API.

What’s something cool you’re working on?

Riona will be the Keynote speaker for TCWorld India

Priyanka’s been working on new episodes of Cloud Bytes. App Engine in a Minute is now up! She’s also working on her series GCP Comics.