Let's Talk Docs

By: SustainOSS
Listen for free

  • Summary

  • Hello and welcome to Let’s Talk Docs! 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.
    © 2023 SustainOSS
    Show more Show less
activate_WEBCRO358_DT_T2
Episodes
  • Episode 10: Mike Jang

    Episode 10: Mike Jang
    May 22 2022
    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:/...
    Show more Show less
    34 mins
  • Episode 9: Zachary Corleissen

    Episode 9: Zachary Corleissen
    May 8 2022
    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.
    Show more Show less
    38 mins
  • Episode 8: Google Season of Docs

    Episode 8: Google Season of Docs
    Apr 25 2022
    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=...
    Show more Show less
    40 mins
Career Success Economics
Show more Show less

What listeners say about Let's Talk Docs

Average customer ratings

Reviews - Please select the tabs below to change the source of reviews.

Audible.com reviews

Amazon reviews
No Reviews are Available