10 episodes
Let's Talk Docs SustainOSS
-
- Technology
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.
-
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
SustainOSS Twitter
SustainOSS Discourse
Let’s Talk Docs Twitter
Portia Burton Twitter
Eric Holscher Twitter
Mike Jang Twitter
Mike Jang LinkedIn
Cobalt
RHCSA/RHCE Red Hat Linux Certification Study Guide, Seventh Edition
Linux Annoyances for Geeks: Getting the Most Flexible System in the World Just the Way You Want It by Michael Jang
Gatsby
Hugo
Write The Docs
The Good Docs Project
Write The Docs Portland 2022
O’Reilly OSCON 2017- UI Text: Simplicity is Difficult
Credits
Executive Produced by Justin Dorfman
Edited by Paul M. Bahr at Peac -
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
SustainOSS Twitter
SustainOSS Discourse
Portia Burton Twitter
Eric Holscher Twitter
Zach Corleissen Twitter
Zach Corleissen Website
Docs for Developers-An Engineer’s Field Guide to Technical Writing (Bhatti, Corleissen, Lambourne, Nunez, Waterhouse)
Stripe
Noah Kantrowitz Twitter
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
Special Guest: Zachary Corleissen.
Sponsored By:
DocumentWrite: Sometimes the tech doesn't speak for itself, and that's why you need stellar documentation.DocumentWrite: Sometimes the tech doesn't speak for itself, and t -
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
SustainOSS Twitter
SustainOSS Discourse
Portia Burton Twitter
Eric Holscher Twitter
Romina Vicente LinkedIn
Ivana Isadora Devcic Twitter
Ivana Isadora Devcic LinkedIn
Erin McKean Twitter
Erin McKean Website
Total -
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
SustainOSS Twitter
SustainOSS Discourse
letstalkdocs@sustainoss.org
Portia Burton Twitter
Eric Holscher Twitter
Amy Burns Twitter
Vercel
The Content Design Book by Sarah Winters
Xamarin
Strategic Writing for UX
The Imagineering Process: Using the Disney Theme Park Design Process to Bring Your Creative Ideas to Life
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
Special Guest: Amy Burns.
Sponsored By:
Sourcegraph: Create living documentation that interacts directly with your code. DocumentWrite: Sometimes the tech doesn't speak for itself, and that's why you need stellar documentation. -
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
SustainOSS Twitter
SustainOSS Discourse
letstalkdocs@sustainoss.org
Portia Burton Twitter
Eric Holscher Twitter
Aisha Blake Website
Aisha Blake Twitch
Aisha Blake Shop
Pluralsight
Getting Paid as a Speaker (Aisha’s blog post)
Speaker Rider by Tatiana Mac
Wavelength Conference
DevEdBookClub Twitter
DevEdBookClub
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
Special Guest: Aisha Blake.
Sponsored By:
Sourcegraph: Create living documentation that interacts directly with your code. DocumentWrite: Sometimes the tech doesn't speak for itself, and that's why you need stellar documentation. -
Beth Aitman
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
SustainOSS Twitter
SustainOSS Discourse
letstalkdocs@sustainoss.org
Portia Burton Twitter
Eric Holscher Twitter
Beth Aitman Twitter
Beth Aitman Website
Beth Aitman LinkedIn
Who Writes the Docs?- with Beth Aitman (YouTube)
Write the Docs Newsletter
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