Let's Talk Docs

Sponsored by Document Write · EthicalAds · Sourcegraph Panelists Portia Burton | Eric Holscher Guest Mike Jang Show Notes Hello and welcome to Let’s Talk Docs, a show where we explore the intersection of technical documentation, open source, and community. Today joining us is Mike Jang, who’s a Staff Technical Writer for Cobalt. To figure out what to write, Mike spends much of his time analyzing and testing new software. He has also written many technical books including multiple editions of RHCSA/RHCE Red Hat Linux Certification Study Guide, as well as the author of Linux Annoyances for Geeks. On this episode, Mike shares his personal journal on how he got started in technical writing and how he spends his time planning and evangelizing. He also shares ideas on how to be a leader as a technical writer and all the different techniques he uses, as well as how to be a part of the community and give back to the community. Download this episode now to find out more! [00:02:00] Find out how Mike got started in technical writing and how he was writing books before he started working at companies as a technical writer. [00:05:14] Mike recently went from working at GitLab where he collaborated with a team of technical writers, and then started working at Cobalt where he was the only writer, and he tells us what the transition was like and what was surprising being the sole writer on a team. [00:08:42] We learn how Mike’s able to effectively get buy-in from his supervisors or co-workers on setting standards. [00:10:29] Mike explains why he prefers using Gatsby even though his team uses Hugo. [00:13:48] Portia wonders how you go about starting a style from scratch. [00:15:20] We find out some of the common misunderstanding’s engineers have about technical writing. [00:17:23] Which parts should be automated in a style guide? [00:19:21] Mike tells us how he finds community when he’s the only technical writer. [00:22:31] We learn some of the motives on why a company would want to open source at least part of their documentation. [00:27:05] Mike shares advice on how someone can improve or level up their skills if this person is the only technical writer on the team. [00:32:08] Mike mentions a talk you should check out that he gave at an O’Reilly OSCON 2017 on, UI Text: Simplicity is Difficult. Quotes [00:07:10] “The biggest challenge for me is learning to become an evangelist for practices I know would help the company I worked for establish itself with good documentation. I needed an elevator pitch.” [00:10:54] “In an ideal world if I had the coding chops, I would use Gatsby because I would then be able to integrate code directly from our front end to ideally make it a seamless experience to transition from our UI to our docs.” [00:13:57] “There are established style guides in the industry and those style guides have created expectations among software users.” [00:16:35] “If I go too far and be too picky, then people will stop asking for help.” [00:22:47] “It’s been essential for me.” [00:22:59] “If the documentation, tooling, and repository were closed source I couldn’t give a full story, but with the open source repository and licensing, I can give a full story and people can volunteer to contribute under the license and understand what’s going on.” Links SustainOSS (https://sustainoss.org/) SustainOSS Twitter (https://twitter.com/SustainOSS?ref_src=twsrc%5Egoogle%7Ctwcamp%5Eserp%7Ctwgr%5Eauthor) SustainOSS Discourse (https://discourse.sustainoss.org/) Let’s Talk Docs Twitter (https://twitter.com/letstalkdocs) Portia Burton Twitter (https://twitter.com/pkafei?lang=en) Eric Holscher Twitter (https://twitter.com/ericholscher) Mike Jang Twitter (https://twitter.com/themikejang?lang=en) Mike Jang LinkedIn (https://www.linkedin.com/authwall?trk=bf&trkInfo=AQG0NqQGrlLjDAAAAYDip7uId1jzmAzjY2N5ahxJmbf8wfZFXwn7Z2Y_h_Lo3ogtC0jPgWsHLsVEL0lA5cZVXtPwVwQneMDLSv-Bo7se5DpTQBr1iPUVtEwKWVy2YnThvzlz53k=&original_referer=&sessionRedirect=https%3A%2F%2Fwww.linkedin.com%2Fin%2Fmijang%2F) Cobalt (https://www.cobalt.io/) RHCSA/RHCE Red Hat Linux Certification Study Guide, Seventh Edition (https://www.mhprofessional.com/9780071841962-usa-rhcsarhce-red-hat-linux-certification-study-guide-seventh-edition-exams-ex200-ex300-group) Linux Annoyances for Geeks: Getting the Most Flexible System in the World Just the Way You Want It by Michael Jang (https://www.amazon.com/_/dp/0596008015?tag=oreilly20-20) Gatsby (https://www.gatsbyjs.com/) Hugo (https://gohugo.io/) Write The Docs (https://www.writethedocs.org/) The Good Docs Project (https://thegooddocsproject.dev/) Write The Docs Portland 2022 (https://www.writethedocs.org/conf/index.html) O’Reilly OSCON 2017- UI Text: Simplicity is Difficult (https://www.oreilly.com/library/view/oscon-2017/9781491976227/video306662.html) Credits Executive Produced by Justin Dorfman (https://www.justindorfman.com/) Edited by Paul M. Bahr at Peachtree Sound (https://www.peachtreesound.com/) Show notes by DeAnn Bahr at Peachtree Sound (https://www.peachtreesound.com/) Cover art by Eriol Fox (https://erioldoesdesign.github.io/) Special Guest: Mike Jang.

Sponsored by Document Write · EthicalAds · Sourcegraph Panelists Portia Burton | Eric Holscher Guest Zachary Corleissen Show Notes Hello and welcome to Let’s Talk Docs, a show where we explore the intersection of technical docs, open source, and community. Here at Let’s Talk Docs, we reach out to folks in the field who are elevating the craft of writing and maintaining docs. Today, joining us as our guest is Zach Corleissen, who’s currently a staff technical writer at Stripe, solving complex documentation challenges and serving as a mentor to other writers. Our conversations bring us to discovering more about documentation, the ethics of documentation, mentoring, and the book Zach co-authored called_, Docs for Developers: An Engineer’s Field Guide to Technical Writing. _Download this episode now to find out more, and until next time, keep writing and shipping those Docs! [00:01:28] Zach tells us the backstory of how their book, Docs for Developers, came together and if there was any inspiration from the group of people that got together to work on it. [00:05:48] Zach explains how their writing is everywhere and nowhere in the book simultaneously and more of a collaborative effort. [00:07:00] We find out what good technical editing looks like. [00:08:51] Eric asks if Zach has been thinking about reviewing doc reviews in an open source contest, or pull requests around documentation, and if they think that’s a form of editing. Eric talks about one of the chapters in the book he really connected with on Feedback. [00:13:34] We hear Zach’s thoughts on what effective mentoring looks like within a documentation organization. [00:15:01] What does good mentoring look like? [00:20:42] Portia, Eric, and Zach chat about who else is having these conversations about documentation and how can we start raising the profile of them because they are so important. [00:27:42] Zach talks about a Twitter conversation with Noah Kantrowitz, who noted some of the roadblocks to funding, open source, and participation and contribution to open source. [00:32:02] We find out what the secret sauce is in Stripe documentation. [00:33:41] The topic of well-funded tooling comes up and Zach shares where you could be spending money on tools. [00:35:56] Zach tells us about their book, Docs for Developers, and to leave a review. Quotes [00:04:12] “All of them assume that you already know how to write, that they begin from the presumption of competence as someone able to document things well, and that’s not a presumption that we can safely make.” [00:08:06] “Write drunk, edit sober.” [00:15:58] “We don’t talk about this nearly enough and it’s one of the other things on my mind about the profession in general is the ethics of documentation.” [00:16:14] “I think about one of the principle ethics of our profession being, tell the truth and good documentation tells the truth.” [00:28:14] “If you are a company who provides managed services, clear documentation isn’t necessarily going to be what generates the need for a managed service.” [00:33:03] “I think it’s the combination with well-funded doc ops, the actual platforming and tooling that delivers the experience of documentation.” Links SustainOSS (https://sustainoss.org/) SustainOSS Twitter (https://twitter.com/SustainOSS?ref_src=twsrc%5Egoogle%7Ctwcamp%5Eserp%7Ctwgr%5Eauthor) SustainOSS Discourse (https://discourse.sustainoss.org/) Portia Burton Twitter (https://mobile.twitter.com/agencycecil) Eric Holscher Twitter (https://twitter.com/ericholscher) Zach Corleissen Twitter (https://twitter.com/zachorsarah?lang=en) Zach Corleissen Website (https://corleissen.com/) Docs for Developers-An Engineer’s Field Guide to Technical Writing (Bhatti, Corleissen, Lambourne, Nunez, Waterhouse) (https://link.springer.com/book/10.1007/978-1-4842-7217-6) Stripe (https://stripe.com/) Noah Kantrowitz Twitter (https://twitter.com/kantrn?ref_src=twsrc%5Egoogle%7Ctwcamp%5Eserp%7Ctwgr%5Eauthor) Credits Executive Produced by Justin Dorfman (https://www.justindorfman.com/) Edited by Paul M. Bahr at Peachtree Sound (https://www.peachtreesound.com/) Show notes by DeAnn Bahr at Peachtree Sound (https://www.peachtreesound.com/) Cover art by Eriol Fox (https://erioldoesdesign.github.io/) Special Guest: Zachary Corleissen.

Sponsored by Document Write · EthicalAds · Sourcegraph Panelists Portia Burton | Eric Holscher Guest Romina Vicente · Ivana Isadora Devcic · Erin McKean 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’re going to talk about Google Season of Docs, everything that’s involved in it, and how you can apply to participate in this fascinating program. Not only do we have the Google Season of Docs team with us, but we also have a contributor. We have Romina Vicente, who is a Noogler, since she just recently joined the team, and she’ll be taking care of the program management with the Season of Docs team with Erin who continues to serve as an advisor to the program. We also have Ivana Devcic, who is a Technical Writer, Editor, and open source advocate with a background in linguistics and translation. And finally, we have Erin McKean, who is the Developer Relations Program Manager at Google Open Source Programs Office, Founder of Wordnik, and an author. Go ahead and download this episode now to find out more and keep writing and shipping those Docs! [00:02:58] We start with Erin telling us the Google Season of Docs origin story and the history around it. [00:05:02] Erin expands on what the obvious need is for documentation. [00:08:03] We find out how Erin chooses organizations to participate in Season of Docs. [00:09:40] Erin tells us what their outreach looks like. [00:11:40] Romina explains what the success picture looks like for documentation and some top things that organizations learned about working with technical writers. [00:16:52] Ivana details her experience as to the problems that documentation is solving for these open source organizations. [00:20:37] Find out how Ivana learned about the Google Season of Docs and what he biggest takeaway was from her experience. [00:24:42] What does analytics 101 look like for a technical writer? [00:30:27] Ivana tells us from her perspective what the process was like when she decided she wanted to participate in a Google Season of Docs. [00:33:16] Romina and Erin talk about dates or procedures if you want to apply for the Google Season of Docs program, as well some changes that were made.. [00:37:25] We end with Erin giving a shout-out to Sarah Maddox and Andrew Chen because without them this program would not exist. Quotes [00:06:51] “Both projects and developers call out that documentation is in need but saying that you need something and actually solving the problem there’s sometimes a big gap between those two things.” [00:07:32] “One of the metrics that we look at is that did the orgs enjoy participating in Season of Docs because maintainers don’t have a lot of spare time.” [00:09:10] We’re looking for diversity across domains, communities, typologies of documentation, so, user guides, API documentation tutorials, and we’re also looking for diversity across audiences.” [00:13:48] “Open Collective was hugely, hugely supportive to projects that really were great at code and bad at bookkeeping.” [00:17:28] “In terms of problems we’re trying to solve, they are usually related to something that may sound simple or obvious but often a big problem such as content gaps on undocumented features, undocumented behavior, undocumented user journeys or paths.” [00:18:37] “I think the curse of knowledge is an underappreciated curse.” [00:20:20] “Checklists are my favorite flavor of lists!” [00:26:31] “A lot of analytics are just proxies for behaviors.” [00:28:15] “A million visitors to your documentation and no users is not a success story.” Links SustainOSS (https://sustainoss.org/) SustainOSS Twitter (https://twitter.com/SustainOSS?ref_src=twsrc%5Egoogle%7Ctwcamp%5Eserp%7Ctwgr%5Eauthor) SustainOSS Discourse (https://discourse.sustainoss.org/) Portia Burton Twitter (https://mobile.twitter.com/agencycecil) Eric Holscher Twitter (https://twitter.com/ericholscher) Romina Vicente LinkedIn (https://www.linkedin.com/in/romina-vicente-43742540) Ivana Isadora Devcic Twitter (https://twitter.com/ivana_isadora?lang=en) Ivana Isadora Devcic LinkedIn (https://www.linkedin.com/in/ivanadevcic) Erin McKean Twitter (https://twitter.com/emckean?ref_src=twsrc%5Egoogle%7Ctwcamp%5Eserp%7Ctwgr%5Eauthor) Erin McKean Website (https://erinmckean.com/) [Totally Weird and Wonderful Words by Erin McKean](https://www.amazon.com/Totally-Weird-Wonderful-Words-McKean/dp/0195312120/ref=sr11?crid=C2STMO7GSECZ&keywords=erin+McKean&qid=1650126495&sprefix=erin+mcken%2Caps%2C89&sr=8-1) [The Secret Lives of Dresses by Erin McKean](https://www.amazon.com/Secret-Lives-Dresses-Erin-McKean/dp/044655572X/ref=sr12?crid=C2STMO7GSECZ&keywords=erin+McKean&qid=1650126495&sprefix=erin+mcken%2Caps%2C89&sr=8-2) [The Hundred Dresses: The Most Iconic Styles of Our Time by Erin McKean](https://www.amazon.com/Hundred-Dresses-Most-Iconic-Styles/dp/1608199762/ref=sr13?crid=C2STMO7GSECZ&keywords=erin+McKean&qid=1650126495&sprefix=erin+mcken%2Caps%2C89&sr=8-3) Wordnik (https://www.wordnik.com/) How to run an open source doc sprint by Sarah Maddox (https://ffeathers.wordpress.com/2019/07/22/how-to-run-an-open-source-doc-sprint/) Documentation maturity audit (https://github.com/google/opendocs/tree/main/audit) Interested in participating in the 2022 Season of Docs? (https://github.com/google/season-of-docs/tree/main/2022-participants) Timeline for Season of Docs 2022 (https://developers.google.com/season-of-docs/docs/timeline) Season of Docs (https://developers.google.com/season-of-docs) Google Open Source Blog (https://opensource.googleblog.com/) Credits Executive Produced by Justin Dorfman (https://www.justindorfman.com/) Edited by Paul M. Bahr at Peachtree Sound (https://www.peachtreesound.com/) Show notes by DeAnn Bahr at Peachtree Sound (https://www.peachtreesound.com/) Cover art by Eriol Fox (https://erioldoesdesign.github.io/) Special Guests: Erin McKean, Ivana Isadora Devcic, and Romina Vicente.

Sponsored by Document Write · EthicalAds · Sourcegraph Panelists Portia Burton | Eric Holscher Guest Amy Burns 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 have joining us as our guest, Amy Burns, who is the Senior Content Developer at Vercel. She’s here to talk about how she got into technical documentation, and she explains four job titles regarding writing and the differences between them. We also hear about what an ideal developer experience looks like, her work on Xamarin, the philosophy of Vercel when it comes to developer experience, and how Amy would advocate her approach of engaging documentation. Download this episode now to find out more, and until next time, keep writing and shipping those Docs! [00:00:52] We hear Amy’s background, how she got into technical documentation, and working at Vercel and GitHub. [00:04:38] Amy tells us about four job titles regarding writing and the differences between them. [00:07:12] Portia asks Amy if she thinks technical writers should a bit about content design and copywriting. [00:09:43] What does an ideal developer experience look like? [00:11:25] Amy talks about The Content Design Book. [00:12:32] Amy worked at Xamarin, an open source mobile platform, and we learn how she got involved in contributing to open source, and she shares suggestions if you want to get more involved in open source. [00:16:40] Find out what it is about documentation that Amy sees as a great way to get involved. [00:18:37] We learn about the philosophy of Vercel when it comes to developer experience, and how the docs are involved there. [00:23:35] Portia brings up business driven goals and talks about Tori Podmajersky’s book, Strategic Writing for UX. [00:25:46] If Amy were to advocate her approach of engaging documentation, she informs us of how she would pitch and advocate this. [00:30:00] We end with Amy sharing a book she wants to read called, The Imagineering Process: Using the Disney Theme Park Design Process to Bring Your Creative Ideas to Life. Quotes [00:05:08] “In my experience, a content developer will be more hands-on with providing code examples or writing bits of code here and there, whereas a technical writer, you might be writing a hundred percent of the time, but that’s not always true.” [00:20:35] “And everybody from CEO down has an opinion on docs, which is great because everyone will pitch in and help, give examples and ways they think the docs could be improved, so it definitely feels like there’s a docs forward culture at Vercel, which is part of the reason I wanted to move there.” Links SustainOSS (https://sustainoss.org/) SustainOSS Twitter (https://twitter.com/SustainOSS?ref_src=twsrc%5Egoogle%7Ctwcamp%5Eserp%7Ctwgr%5Eauthor) SustainOSS Discourse (https://discourse.sustainoss.org/) letstalkdocs@sustainoss.org (mailto:letstalkdocs@sustainoss.org) Portia Burton Twitter (https://mobile.twitter.com/agencycecil) Eric Holscher Twitter (https://twitter.com/ericholscher) Amy Burns Twitter (https://twitter.com/timeyoutakeit?lang=en) Vercel (https://vercel.com/) The Content Design Book by Sarah Winters (https://contentdesign.london/store/the-content-design-book/) Xamarin (https://dotnet.microsoft.com/en-us/apps/xamarin) Strategic Writing for UX (https://www.oreilly.com/library/view/strategic-writing-for/9781492049388/) The Imagineering Process: Using the Disney Theme Park Design Process to Bring Your Creative Ideas to Life (https://www.amazon.com/Imagineering-Process-Disney-Creative-Toolbox/dp/168390138X) Credits Executive Produced by Justin Dorfman (https://www.justindorfman.com/) Edited by Paul M. Bahr at Peachtree Sound (https://www.peachtreesound.com/) Show notes by DeAnn Bahr at Peachtree Sound (https://www.peachtreesound.com/) Cover art by Eriol Fox (https://erioldoesdesign.github.io/) Special Guest: Amy Burns.

Sponsored by Document Write · EthicalAds · Sourcegraph Panelists Portia Burton | Eric Holscher Guest Aisha Blake 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 have joining us Aisha Blake, Director of Developer Relations at Pluralsight, as well as a theater kid turned tech community leader, speaker, conference organizer, and teacher. Aisha explains how a Developer Relations Engineer is one flavor of a whole range of titles. She shares her story of how she sees a lot of connections to being in theater as a kid and how getting into developer relations played out for her. We also learn how documentation is such a vital part of the developer experience, how spaces such as Discord and Twitch compliment documentation, and Aisha’s blog post, “Getting Paid as a Speaker.” Download this episode now to find out more, and until next time, keep writing and shipping those Docs! [00:01:24] Aisha fills us in what a Developer Relations Engineer is. [00:10:06] Eric wonders if Aisha views documentation as owned within this new org that she’s imagining as part of the developer experience and if documentation is part of that in her mind. [00:12:39] Aisha shares her story from starting as a theatre kid and getting into developer relations. [00:19:34] We hear about a blog post Aisha wrote called, “Getting Paid as a Speaker, and a model that Marlena Compton did through Wavelength. [00:26:58] Aisha has a Twitch channel and tells us about wanting to do a show about developer education. [00:28:48] Find out how spaces such as Discord and Twitch compliment documentation. [00:32:51] Portia, Eric, and Aisha chat about the DevEdBookClub and the sense of community there and in the Twitter space there was a bunch of celebrities in the chat. [00:36:11] Portia announces a really cool sticker Aisha is selling in her shop that you should go check out. Quotes [00:05:54] “In an ideal world. I’d love to see more companies moving towards breaking developer experience out into its own org.” [00:09:29] “Part of that conversation of me coming into the role was that I would be able to really shape our metrics and our goals along with marketing leadership.” [00:11:43] “I believe that documentation is such a vital part of the developer experience that if you’re going to have a developer experience team, then documentation has to be the pillar of it.” [00:15:42] “I tell people all the time that I remember almost nothing from my degree.” [00:23:45] “If I’m being asked to speak, I expect to be paid because you’re requesting my services.” Links SustainOSS (https://sustainoss.org/) SustainOSS Twitter (https://twitter.com/SustainOSS?ref_src=twsrc%5Egoogle%7Ctwcamp%5Eserp%7Ctwgr%5Eauthor) SustainOSS Discourse (https://discourse.sustainoss.org/) letstalkdocs@sustainoss.org (mailto:letstalkdocs@sustainoss.org) Portia Burton Twitter (https://mobile.twitter.com/agencycecil) Eric Holscher Twitter (https://twitter.com/ericholscher) Aisha Blake Website (https://aisha.codes/) Aisha Blake Twitch (https://www.twitch.tv/aishacodes) Aisha Blake Shop (https://aisha.codes/shop) Pluralsight (https://www.pluralsight.com/) Getting Paid as a Speaker (Aisha’s blog post) (https://aisha.codes/getting-paid-as-a-speaker/) Speaker Rider by Tatiana Mac (https://gist.github.com/tatianamac/493ca668ee7f7c07a5b282f6d9132552) Wavelength Conference (https://wavelengthconf.com/) DevEdBookClub Twitter (https://twitter.com/DevEdBookClub) DevEdBookClub (https://dev.to/devedbookclub) Credits Executive Produced by Justin Dorfman (https://www.justindorfman.com/) Edited by Paul M. Bahr at Peachtree Sound (https://www.peachtreesound.com/) Show notes by DeAnn Bahr at Peachtree Sound (https://www.peachtreesound.com/) Cover art by Eriol Fox (https://erioldoesdesign.github.io/) Special Guest: Aisha Blake.

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 SustainOSS (https://sustainoss.org/) SustainOSS Twitter (https://twitter.com/SustainOSS?ref_src=twsrc%5Egoogle%7Ctwcamp%5Eserp%7Ctwgr%5Eauthor) SustainOSS Discourse (https://discourse.sustainoss.org/) letstalkdocs@sustainoss.org (mailto:letstalkdocs@sustainoss.org) Portia Burton Twitter (https://mobile.twitter.com/agencycecil) Eric Holscher Twitter (https://twitter.com/ericholscher) Beth Aitman Twitter (https://twitter.com/baitman?lang=en) Beth Aitman Website (https://bethaitman.com/) Beth Aitman LinkedIn (https://ch.linkedin.com/in/bethaitman) Who Writes the Docs?- with Beth Aitman (YouTube) (https://www.writethedocs.org/videos/portland/2018/who-writes-the-docs-beth-aitman/) Write the Docs Newsletter (https://www.writethedocs.org/blog/archive/tag/newsletter/) Riona MacNamara-As Good As It Gets: Why Better Trumps Best (YouTube) (https://www.writethedocs.org/videos/eu/2016/pretty-hurts-why-better-trumps-best-riona-macnamara/) A practical guide to making good documentation with Beth Aitman (HaskellerZ meetup) (https://docs.google.com/presentation/d/1r4gLfgPpnT6KFkWn0VEsoIUwiwhVaOYS0CJeSWja0kc/edit#slide=id.p) essential Waitrose (HaskellerZ docs talks) (https://docs.google.com/presentation/d/1r4gLfgPpnT6KFkWn0VEsoIUwiwhVaOYS0CJeSWja0kc/edit#slide=id.g474e3d5afc_0_145) Credits Executive Produced by Justin Dorfman (https://www.justindorfman.com/) Edited by Paul M. Bahr at Peachtree Sound (https://www.peachtreesound.com/) Show notes by DeAnn Bahr at Peachtree Sound (https://www.peachtreesound.com/) Cover art by Eriol Fox (https://erioldoesdesign.github.io/) Special Guest: Beth Aitman.

Sponsored by Document Write · EthicalAds · Sourcegraph Panelists Portia Burton | Eric Holscher Guest Swapnil Ogale Show Notes Hello and welcome to Let’s Talk Docs, the show where we talk about documentation, open source, tech, and the intersection of the three. Our special guest today is Swapnil Ogale, who has over 16 years of technical documentation experience across a range of industries in Australia and globally. Currently, he works as Redocly’s Technical Writer Advocate, pursuing his passion for writing, along with advocating for the docs-as-code approach for product content. He initiated the Write the Docs community in Australia in 2016 and has been organizing local meetups and annual national conferences. Today, Swapnil shares his journey of getting into technical writing and goes in-depth about what technical writers do and how they spend their time. We also learn more about his passion for speaking at conferences about documentation, what motivated him to start the Write the Docs community in Australia, and how the Google Season of Docs is a fantastic way to give back to the community and pick up so much valuable experience. Go ahead and download this episode now to learn more! [00:00:56] Swapnil shares his story of how he got into technical writing. [00:03:00] Swapnil received a technical communication certificate and he tells us the important thing he learned from that program that he uses today. [00:07:03] We learn what kind of value Swapnil gained from speaking at conferences and what the benefit is. [00:10:26] Portia brings up how Swapnil advocates for himself and he explains the importance of this. [00:12:27] Portia asks Swapnil to talk about what developers should know about technical writers, what technical writers do, and how they spend their time. [00:15:16] Swapnil speaks at conferences about documentation, and he explains some of the reactions he gets after he gives these presentations. [00:20:46] We find out what motivated Swapnil to start the Write the Docs Australia community, and he shares how other people can get involved in doing this kind of community building in their own community. [00:24:02] Swapnil explains what the global perspective is. [00:28:03] We learn how the Google Season of Docs works and how a writer knows that they’re ready to contribute to open source projects. [00:33:23] We end up finding out where you can follow Swapnil online, he tells us he’s Co-authoring a second edition of the book, _Technical Writing Process, and he’s currently learning Australian Sign Language. Quotes [00:14:29] “Writing is only 30% of my day and it’s the other things around it that actually adds value to that documentation.” [00:16:36] “So that’s that notion of ‘we didn’t know you could do that is what I’m trying to debunk.” [00:32:26] “Google Season of Docs is coming and they’re starting applications. You’ll never find a better way to get more experience if you’ve never done documentation before and worked on a global team.” Links SustainOSS (https://sustainoss.org/) SustainOSS Twitter (https://twitter.com/SustainOSS?ref_src=twsrc%5Egoogle%7Ctwcamp%5Eserp%7Ctwgr%5Eauthor) SustainOSS Discourse (https://discourse.sustainoss.org/) Portia Burton Twitter (https://mobile.twitter.com/agencycecil) Eric Holscher Twitter (https://twitter.com/ericholscher) Swapnil Ogale Twitter (https://twitter.com/swapnilogale) Swapnil Ogale LinkedIn (https://www.linkedin.com/in/swapnilogale/) Redocly (https://redoc.ly/) Technical Writing Process (https://technicalwritingprocess.com/) Google Open Source Blog: Announcing Season of Docs 2022 (https://opensource.googleblog.com/2022/02/Announcing%20Season%20of%20Docs%202022.html) Auslan (Australian Sign Language) (https://www.startasl.com/auslan/) Credits Executive Produced by Justin Dorfman (https://www.justindorfman.com/) Edited by Paul M. Bahr at Peachtree Sound (https://www.peachtreesound.com/) Show notes by DeAnn Bahr at Peachtree Sound (https://www.peachtreesound.com/) Cover art by Eriol Fox (https://erioldoesdesign.github.io/) Special Guest: Swapnil Ogale.

Sponsored by Document Write · EthicalAds · Sourcegraph Panelists Portia Burton | Eric Holscher Guest Fabrizio Ferri-Benedetti Show Notes Hello and welcome to Let’s Talk Docs, the show where we talk about documentation, open source, tech, and the intersection of the three. Today, our special guest is Fabrizio Benedetti, who’s a Senior Staff Technical Writer at Splunk, and previously was a technical journalist and studied psychology. Fabrizio takes us through his journey of technical writing and shares some helpful tips if becoming a technical writer interests you. We also find out more about Fabrizio’s “Columbo Technique for Technical Writers,” he explains docs-as-code, and we learn about the children’s story he’s doing on OpenTelemetry. Go ahead and download this episode not to find out more! [00:00:43] Fabrizio tells us how he got into technical writing and the path that led him to where he’s at in his career. [00:06:55] We learn more about the Columbo Technique for technical writers. [00:09:24] Portia wonders if junior technical writers struggle with talking to the engineer, and Fabry tells us some cliché questions that newer technical writers might ask. [00:12:14] Fabrizio explains docs-as-code. [00:17:28] We find out some skills Fabrizio picked up as a tech journalist that he still uses today. [00:20:54] Fabrizio shares some advice if you’re interested in becoming a technical writer. [00:25:46] We hear Fabrizio explain about improving the tool chain. [00:31:31] Fabrizio talks about working on a children’s story on OpenTelemetry. [00:34:40] Find out where you can follow Fabrizio online. Quotes [00:03:57] “With the transition to tech writing, there’s something about precision in scientific language.” [00:07:29] “I was trying to think of something that could capture the essence of what I do on a daily basis and this image of the detective came to my mind, and I immediately thought of Columbo.” [00:13:59] “You can do docs-as-code with pretty much any markup language.” [00:19:57] “It’s really hard to document something that doesn’t make sense.” [00:21:14] “Some general tips I would say is to start building your own website which could also contain your own portfolio.” [00:26:04] “If I saw the resume of a technical writer wannabe, former Python developer that created a small script to convert tables between formats flawlessly, I would hire that guy.” Links SustainOSS (https://sustainoss.org/) SustainOSS Twitter (https://twitter.com/SustainOSS?ref_src=twsrc%5Egoogle%7Ctwcamp%5Eserp%7Ctwgr%5Eauthor) SustainOSS Discourse (https://discourse.sustainoss.org/) Portia Burton Twitter (https://mobile.twitter.com/agencycecil) Eric Holscher Twitter (https://twitter.com/ericholscher) Fabrizio Ferri-Benedetti Twitter (https://twitter.com/remoquete) Fabrizio Ferri-Benedetti LinkedIn (https://www.linkedin.com/in/fabrizioferri/) Fabrizio Ferri-Benedetti Blog (https://passo.uno/) Fabrizio Ferri-Benedetti GitHub (https://github.com/theletterf) Splunk (https://www.splunk.com/) Columbo Technique (https://passo.uno/the-columbo-technique-for-technical-writers/) OpenTelemetry (https://opentelemetry.io/) Credits Executive Produced by Justin Dorfman (https://www.justindorfman.com/) Edited by Paul M. Bahr at Peachtree Sound (https://www.peachtreesound.com/) Show notes by DeAnn Bahr at Peachtree Sound (https://www.peachtreesound.com/) Cover art by Eriol Fox (https://erioldoesdesign.github.io/) Special Guest: Fabrizio Ferri-Benedetti.

Sponsored by Document Write · EthicalAds · Sourcegraph Panelists Portia Burton | Eric Holscher Guest Tom Johnson Show Notes Hello and welcome to Let’s Talk Docs, the show where we’ll talk about documentation, open source, tech, and the intersection of the three. Today, we’re talking to Tom Johnson, who’s a tech writer and has worked at both startups and big tech for the past 17 years. He has a blog called, I’d Rather be Writing, which he’ll tell us about, as well as an API doc course that provides a lot of free information on how to write API documentation. Tom goes in detail about the checklists he made that make for good API documentation, the research he did, and the feedback he received about them. We’ll find out more about the Pronovix Developer Portal Awards that Tom participated in and what he focused on when evaluating each developer’s portals, how receiving an MFA in non-fiction writing personally helped him, and something he’s currently working on that he’s excited about. Go ahead and download this episode now to learn more! [00:01:02] Tom explains his API checklists and what prompted him to do it. [00:04:38] We learn about the Pronovix Developer Portal Awards and the approach that was taken when evaluating these knowledge centers. We also learn what is bad in terms of the developer portal. [00:07:17] Find out what the characteristics are of good “curb appeal” when it comes to developer documentation. [00:11:58] Eric wonders how Tom gets the user’s perspective when he’s evaluating the quality and if he had a specific user in mind for the awards. [00:15:11] Portia wonders the best way to interact with users if you are a small start-up. [00:20:34] We learn about the feedback Tom got on his API checklist. [00:25:56] The conversation takes a turn to finding out Tom’s origin story, how he ended up writing about documentation, and keeping a blog since 2006. [00:29:01] Tom mentioned he received an MFA in non-fiction writing and he tells us how it’s personally helped him shape his writing. [00:36:50] We end with Tom sharing with us a series he’s currently working on. Quotes [00:06:07] “It’s one of those things where you know it when you see it.” [00:31:53] “There’s always things that are interesting to explore.” [00:33:28] “Write the Docs is an international community of people who are really passionate about writing and finding each other, and that didn’t exist before the docs so that’s really big and meaningful.” Links SustainOSS (https://sustainoss.org/) SustainOSS Twitter (https://twitter.com/SustainOSS?ref_src=twsrc%5Egoogle%7Ctwcamp%5Eserp%7Ctwgr%5Eauthor) SustainOSS Discourse (https://discourse.sustainoss.org/) Portia Burton Twitter (https://mobile.twitter.com/agencycecil) Eric Holscher Twitter (https://twitter.com/ericholscher) Tom Johnson Twitter (https://twitter.com/tomjohnson) Tom Johnson LinkedIn (https://www.linkedin.com/in/tomjoht/) I’d Rather Be Writing blog (https://idratherbewriting.com/) Measuring documentation quality through user feedback (https://pronovix.com/blog/best-developer-portals-2021) Pronovix Developer Awards (https://pronovix.com/blog/best-developer-portals-2021) Five basketball strategies and how they might apply to tech comm (https://idratherbewriting.com/blog/basketball-strategies-applicability-to-tech-comm#1-the-shooting-bigs) A hypothesis about influence on the web and the workplace (https://idratherbewriting.com/web-and-workplace-influence/part1-introduction-to-influencers.html) My life story, or reflections on what shaped my life’s career trajectory (https://idratherbewriting.com/blog/life-story-what-shapes-your-lifes-trajectory/) Documenting APIs: A guide for technical writers and engineers (https://idratherbewriting.com/learnapidoc/) Quality checklist for API documentation (https://idratherbewriting.com/learnapidoc/docapis_quality_checklist.html) Credits Executive Produced by Justin Dorfman (https://www.justindorfman.com/) Edited by Paul M. Bahr at Peachtree Sound (https://www.peachtreesound.com/) Show notes by DeAnn Bahr at Peachtree Sound (https://www.peachtreesound.com/) Cover art by Eriol Fox (https://erioldoesdesign.github.io/) Special Guest: Tom Johnson.

Sponsored by Document Write · EthicalAds · Sourcegraph Panelists Portia Burton | Eric Holscher Guest Megan Sullivan Show Notes Hello and welcome to Let’s Talk Docs! This is our first episode and we’re so happy you’re joining us. On this podcast, we’ll be sharing with you a new concept around documentation and sustainability. We’re going to talk about how you can leverage documentation, how you can leverage content to bring more people, more attention, and more funding to your products. We’ll talk to experts who know how to write content engagingly, interview people who speak about the importance of content having goals, and talk to people who have successfully built projects, used excellent documentation, and used the content as the pillar of their success. Our panelists are Portia Burton, who is the owner of DocumentWrite, and Eric Holscher, who is the Co-Founder of Read the Docs, Write the Docs, EthicalAds, and PyCascades. We are super excited to have as our guest, Megan Sullivan, who is a Developer Educator at Apollo. Megan shares her background and story about studying CS, going into teaching CS courses, and how putting the two together helped her become a more confident professional developer and create a path for others with an educational background. We find out about a manual Megan wrote about herself, what “Being Glue” means, and she shares advice if you’re the person who’s interested in taking this journey similar to what she’s doing in technical writing and education. Go ahead and download this episode now! [00:01:27] We hear what Megan did before specializing in technical documentation. [00:06:16] Megan mentioned teaching people to code when she did the AmeriCorps program, and Portia wonders if she were to go back and design a CS program how would she do it that would be engaging. [00:10:44] Megan shares what inspired her to get into technical writing. [00:14:51] On Megan’s website, she has a page dedicated to accessibility, and she tells us about the manual she wrote about herself and she mentions Steph Smith’s website. [00:16:51] Find out what inspired Megan to publish her manual and share it. [00:18:28] Portia talks about notetaking and “Being Glue,” and asks Megan’s opinion on what she would say about women who want to help out their team but don’t want to be like glue. [00:23:20] We hear Megan’s thoughts on ways she thinks documentation can be taken more seriously, and how can we get people in college to get excited and build that status in the industry to get people excited. [00:27:44] Megan shares some advice if you’re interested in following this kind of path of teaching technical stuff, and she tells us about a great book, Docs for Developers. [00:32:25] We end with some shout-outs and cool things happening that you should check out. Quotes [00:07:40] “There are a lot of different ways that knowing how to code can help you in different industries.” [00:09:02] “Right when I started that program was around the time the movie The Social Network came out, and I thought if this is what being in tech is like I want no part in that.” [00:14:21] “I like trying to figure out how to make things look pretty and I’m not good at it, but I like thinking about that and thinking about accessibility is something I’m really interested in.” [00:23:42] “I think a good way to get people to take documentation seriously is to talk about what’s hard about documentation.” Links SustainOSS (https://sustainoss.org/) SustainOSS Twitter (https://twitter.com/SustainOSS?ref_src=twsrc%5Egoogle%7Ctwcamp%5Eserp%7Ctwgr%5Eauthor) SustainOSS Discourse (https://discourse.sustainoss.org/) Portia Burton Twitter (https://mobile.twitter.com/agencycecil) Eric Holscher Twitter (https://twitter.com/ericholscher?ref_src=twsrc%5Egoogle%7Ctwcamp%5Eserp%7Ctwgr%5Eauthor) DocumentWrite (https://documentwrite.dev/about/) Write the Docs (https://www.writethedocs.org/) Read the Docs (https://readthedocs.org/) EthicalAds (https://www.ethicalads.io/) PyCascades (https://2022.pycascades.com/) Megan Sullivan Twitter (https://twitter.com/meganesulli) Megan Sullivan LinkedIn (https://www.linkedin.com/in/meganesu) Megan Sullivan Website (https://meganesulli.com/) Apollo (https://www.apollographql.com/) DEV Community (https://dev.to/) The Social Network (https://www.imdb.com/title/tt1285016/) Steph Smith Website (https://stephsmith.io/) Personal User Manual-Megan Sullivan (https://meganesulli.com/manual/) Being Glue-Tanya Reilly (https://noidea.dog/glue) GatsbyCamp Fall-Docs for Everyone-Megan Sullivan (YouTube) (https://www.youtube.com/watch?v=HnBNbG2Csv8) The Secret History of Women in Coding (The New York Times Magazine) (https://www.nytimes.com/2019/02/13/magazine/women-coding-computer-programming.html) Docs for Developers: An Engineer’s Field Guide to Technical Writing (https://www.amazon.com/Docs-Developers-Engineers-Technical-Writing/dp/1484272161/ref=sr_1_1?crid=1LTLCGI1CMX4U&keywords=Docs+for+Developers&qid=1645316465&sprefix=docs+for+developers%2Caps%2C71&sr=8-1) Write the Docs Portland 2022 (https://www.writethedocs.org/conf/portland/2022/cfp/) DevEdBookClub Twitter (https://twitter.com/devedbookclub) Credits Executive Produced by Justin Dorfman (https://www.justindorfman.com/) Edited by Paul M. Bahr at Peachtree Sound (https://www.peachtreesound.com/) Show notes by DeAnn Bahr at Peachtree Sound (https://www.peachtreesound.com/) Cover art by Eriol Fox (https://erioldoesdesign.github.io/) Special Guest: Megan Sullivan.