Let's Talk Docs

• Episode 10: Mike Jang

  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.

  --------  

  34:17
• Episode 9: Zachary Corleissen

  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.

  --------  

  38:09
• Episode 8: Google Season of Docs

  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.

  --------  

  39:41
• Episode 7: Amy Burns

  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/) [email protected] (mailto:[email protected]) 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.

  --------  

  33:19
• Episode 6: Aisha Blake

  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/) [email protected] (mailto:[email protected]) 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.

  --------  

  38:24

More Technology podcasts

Trending Technology podcasts

About Let's Talk Docs

Let's Talk Docs: Podcasts in Family