Episode 5
Beth Aitman
March 24th, 2022
40 mins 56 secs
Season 1
Your Hosts
Special Guest
About this Episode
Sponsored by
Document Write · EthicalAds · Sourcegraph
Panelists
Portia Burton | Eric Holscher
Guest
Beth Aitman
Show Notes
Hello and welcome to Let’s Talk Docs, a show where we explore the intersection of technical docs, open source, and community. Today, we are so excited to have as our guest, Beth Aitman, who is a Senior Technical Writer at Google, where she works to improve the developer experience for Site Reliability Engineers, and she’s also the editor of the Write the Docs newsletter. Beth’s interested in the intersection between UX and writing and is passionate about teaching developers how to write good docs. We find out how Beth got into technical writing and the process of figuring out what the reader needs from the documentation. Beth goes in depth about what ineffective documentation looks like, what “documentation smells” are, and she shares advice about why focusing your energy is important for a team writing documentation. Go ahead and download this episode now to find out more!
[00:01:22] We learn how Beth got into technical writing and how she figured out that documentation was really her professional home.
[00:06:37] Beth shares with us a way to diplomatically express to stakeholders that documentation can’t fix this.
[00:11:24] Portia asks Beth how she figures out what the reader needs from the documentation.
[00:16:39] Beth tells us about a conversation that comes up quite often on the Write the Docs slack, and she talks about the product message.
[00:22:00] We find out what ineffective documentation looks like and what “documentation smells” are, and Beth tells us about a great talk by Riona MacNamara about what documentation is for.
[00:30:23] Beth talks about teaching materials that Google publishes to help people with documentation.
[00:31:44] Since Beth has worked at several companies, she explains the differences between writing documentation for a smaller company as opposed to a FAANG, which stands for Facebook, Amazon, Apple, Netflix, and Google.
[00:37:43] We hear some advice from Beth for a team writing documentation, and she tells us to check out the Write the Docs newsletter.
Quotes
[00:03:08] “Writing is not difficult and super scary and it’s easy for people to contribute.”
[00:05:43] “You can take a complex thing and you can clarify it, but you can’t reduce the complexity.”
[00:08:45] “One of the things that has worked really well for me in the past in getting more people interested in documentation is helping them see that as part of the problem that they’re solving.”
[00:10:01] “In the definition of done, the feature is done once it is documented and usable.”
[00:18:37] “There’s a lot of the things that tech writers end up getting into this messy reality of a theory hits practice.”
[00:21:27] “It’s also a practice of being diplomatic too and I wish there was a more sophisticated way of saying this but It’s really hard to call someone’s baby ugly.”
[00:27:01] “Marketing is this whole other skillset that I do not have.”
[00:32:30] “At Google, there is a good culture of people caring about documentation and the tooling is good.”
[00:33:26] “I think having outdated documentation is slightly better, but not by much.”
[00:35:47] “A product manager recently told me it isn’t prioritization until it hurts.”
Links
Who Writes the Docs?- with Beth Aitman (YouTube)
Riona MacNamara-As Good As It Gets: Why Better Trumps Best (YouTube)
A practical guide to making good documentation with Beth Aitman (HaskellerZ meetup)
essential Waitrose (HaskellerZ docs talks)
Credits
- Executive Produced by Justin Dorfman
- Edited by Paul M. Bahr at Peachtree Sound
- Show notes by DeAnn Bahr at Peachtree Sound
- Cover art by Eriol Fox
