Portia Burton | Eric Holscher
\n\nMike Jang
\n\nHello 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!
\n\n[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.
\n\n[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.
\n\n[00:08:42] We learn how Mike’s able to effectively get buy-in from his supervisors or co-workers on setting standards.
\n\n[00:10:29] Mike explains why he prefers using Gatsby even though his team uses Hugo.
\n\n[00:13:48] Portia wonders how you go about starting a style from scratch.
\n\n[00:15:20] We find out some of the common misunderstanding’s engineers have about technical writing.
\n\n[00:17:23] Which parts should be automated in a style guide?
\n\n[00:19:21] Mike tells us how he finds community when he’s the only technical writer.
\n\n[00:22:31] We learn some of the motives on why a company would want to open source at least part of their documentation.
\n\n[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.
\n\n[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.
\n\n[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.”
\n\n[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.”
\n\n[00:13:57] “There are established style guides in the industry and those style guides have created expectations among software users.”
\n\n[00:16:35] “If I go too far and be too picky, then people will stop asking for help.”
\n\n[00:22:47] “It’s been essential for me.”
\n\n[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.”
\n\nRHCSA/RHCE Red Hat Linux Certification Study Guide, Seventh Edition
\n\n\n\n\n\n\n\n\n\n\n\n\n\nO’Reilly OSCON 2017- UI Text: Simplicity is Difficult
\n\nSpecial Guest: Mike Jang.
","summary":"In 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, all the different techniques he uses, and how to be a part of the community and give back to the community.","date_published":"2022-05-22T10:00:00.000-04:00","attachments":[{"url":"https://chrt.fm/track/28DGC9/aphid.fireside.fm/d/1437767933/98ecf3aa-9157-4278-a770-0bae0b9b7d99/42fb177c-97c3-469a-923f-cd65a3b6f083.mp3","mime_type":"audio/mpeg","size_in_bytes":65826518,"duration_in_seconds":2057}]},{"id":"bf9f1440-e391-480a-8017-be60ead9c856","title":"Episode 9: Zachary Corleissen","url":"https://ltd-podcast.sustainoss.org/9","content_text":"\nSponsored by Document Write · EthicalAds · Sourcegraph\n\n\nPanelists\n\nPortia Burton | Eric Holscher\n\nGuest\n\nZachary Corleissen\n\nShow Notes\n\nHello 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! \n\n[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. \n\n[00:05:48] Zach explains how their writing is everywhere and nowhere in the book simultaneously and more of a collaborative effort.\n\n[00:07:00] We find out what good technical editing looks like.\n\n[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.\n\n[00:13:34] We hear Zach’s thoughts on what effective mentoring looks like within a documentation organization.\n\n[00:15:01] What does good mentoring look like?\n\n[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. \n\n[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.\n\n[00:32:02] We find out what the secret sauce is in Stripe documentation.\n\n[00:33:41] The topic of well-funded tooling comes up and Zach shares where you could be spending money on tools.\n\n[00:35:56] Zach tells us about their book, Docs for Developers, and to leave a review.\n\nQuotes\n\n[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.”\n\n[00:08:06] “Write drunk, edit sober.”\n\n[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.”\n\n[00:16:14] “I think about one of the principle ethics of our profession being, tell the truth and good documentation tells the truth.”\n\n[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.”\n\n[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.”\n\nLinks\n\nSustainOSS\n\nSustainOSS Twitter\n\nSustainOSS Discourse\n\nPortia Burton Twitter\n\nEric Holscher Twitter\n\nZach Corleissen Twitter\n\nZach Corleissen Website\n\nDocs for Developers-An Engineer’s Field Guide to Technical Writing (Bhatti, Corleissen, Lambourne, Nunez, Waterhouse)\n\nStripe\n\nNoah Kantrowitz Twitter\n\nCredits\n\n\nExecutive Produced by Justin Dorfman\nEdited by Paul M. Bahr at Peachtree Sound\nShow notes by DeAnn Bahr at Peachtree Sound\nCover art by Eriol Fox\nSpecial 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 that's why you need stellar documentation.","content_html":"Portia Burton | Eric Holscher
\n\nZachary Corleissen
\n\nHello 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!
\n\n[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.
\n\n[00:05:48] Zach explains how their writing is everywhere and nowhere in the book simultaneously and more of a collaborative effort.
\n\n[00:07:00] We find out what good technical editing looks like.
\n\n[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.
\n\n[00:13:34] We hear Zach’s thoughts on what effective mentoring looks like within a documentation organization.
\n\n[00:15:01] What does good mentoring look like?
\n\n[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.
\n\n[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.
\n\n[00:32:02] We find out what the secret sauce is in Stripe documentation.
\n\n[00:33:41] The topic of well-funded tooling comes up and Zach shares where you could be spending money on tools.
\n\n[00:35:56] Zach tells us about their book, Docs for Developers, and to leave a review.
\n\n[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.”
\n\n[00:08:06] “Write drunk, edit sober.”
\n\n[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.”
\n\n[00:16:14] “I think about one of the principle ethics of our profession being, tell the truth and good documentation tells the truth.”
\n\n[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.”
\n\n[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.”
\n\nSpecial Guest: Zachary Corleissen.
Sponsored By:
Portia Burton | Eric Holscher
\n\nRomina Vicente · Ivana Isadora Devcic · Erin McKean
\n\nHello 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!
\n\n[00:02:58] We start with Erin telling us the Google Season of Docs origin story and the history around it.
\n\n[00:05:02] Erin expands on what the obvious need is for documentation.
\n\n[00:08:03] We find out how Erin chooses organizations to participate in Season of Docs.
\n\n[00:09:40] Erin tells us what their outreach looks like.
\n\n[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.
\n\n[00:16:52] Ivana details her experience as to the problems that documentation is solving for these open source organizations.
\n\n[00:20:37] Find out how Ivana learned about the Google Season of Docs and what he biggest takeaway was from her experience.
\n\n[00:24:42] What does analytics 101 look like for a technical writer?
\n\n[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.
\n\n[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..
\n\n[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.
\n\n[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.”
\n\n[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.”
\n\n[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.”
\n\n[00:13:48] “Open Collective was hugely, hugely supportive to projects that really were great at code and bad at bookkeeping.”
\n\n[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.”
\n\n[00:18:37] “I think the curse of knowledge is an underappreciated curse.”
\n\n[00:20:20] “Checklists are my favorite flavor of lists!”
\n\n[00:26:31] “A lot of analytics are just proxies for behaviors.”
\n\n[00:28:15] “A million visitors to your documentation and no users is not a success story.”
\n\nTotally Weird and Wonderful Words by Erin McKean
\n\nThe Secret Lives of Dresses by Erin McKean
\n\nThe Hundred Dresses: The Most Iconic Styles of Our Time by Erin McKean
\n\n\n\nHow to run an open source doc sprint by Sarah Maddox
\n\n\n\nInterested in participating in the 2022 Season of Docs?
\n\nTimeline for Season of Docs 2022
\n\n\n\n\n\nSpecial Guests: Erin McKean, Ivana Isadora Devcic, and Romina Vicente.
Sponsored By:
Portia Burton | Eric Holscher
\n\nAmy Burns
\n\nHello 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!
\n\n[00:00:52] We hear Amy’s background, how she got into technical documentation, and working at Vercel and GitHub.
\n\n[00:04:38] Amy tells us about four job titles regarding writing and the differences between them.
\n\n[00:07:12] Portia asks Amy if she thinks technical writers should a bit about content design and copywriting.
\n\n[00:09:43] What does an ideal developer experience look like?
\n\n[00:11:25] Amy talks about The Content Design Book.
\n\n[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.
\n\n[00:16:40] Find out what it is about documentation that Amy sees as a great way to get involved.
\n\n[00:18:37] We learn about the philosophy of Vercel when it comes to developer experience, and how the docs are involved there.
\n\n[00:23:35] Portia brings up business driven goals and talks about Tori Podmajersky’s book, Strategic Writing for UX.
\n\n[00:25:46] If Amy were to advocate her approach of engaging documentation, she informs us of how she would pitch and advocate this.
\n\n[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.
\n\n[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.”
\n\n[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.”
\n\nThe Content Design Book by Sarah Winters
\n\n\n\n\n\n\n\nSpecial Guest: Amy Burns.
Sponsored By:
Portia Burton | Eric Holscher
\n\nAisha Blake
\n\nHello 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!
\n\n[00:01:24] Aisha fills us in what a Developer Relations Engineer is.
\n\n[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.
\n\n[00:12:39] Aisha shares her story from starting as a theatre kid and getting into developer relations.
\n\n[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.
\n\n[00:26:58] Aisha has a Twitch channel and tells us about wanting to do a show about developer education.
\n\n[00:28:48] Find out how spaces such as Discord and Twitch compliment documentation.
\n\n[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.
\n\n[00:36:11] Portia announces a really cool sticker Aisha is selling in her shop that you should go check out.
\n\n[00:05:54] “In an ideal world. I’d love to see more companies moving towards breaking developer experience out into its own org.”
\n\n[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.”
\n\n[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.”
\n\n[00:15:42] “I tell people all the time that I remember almost nothing from my degree.”
\n\n[00:23:45] “If I’m being asked to speak, I expect to be paid because you’re requesting my services.”
\n\nGetting Paid as a Speaker (Aisha’s blog post)
\n\n\n\n\n\n\n\n\n\nSpecial Guest: Aisha Blake.
Sponsored By:
Portia Burton | Eric Holscher
\n\nBeth Aitman
\n\nHello 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!
\n\n[00:01:22] We learn how Beth got into technical writing and how she figured out that documentation was really her professional home.
\n\n[00:06:37] Beth shares with us a way to diplomatically express to stakeholders that documentation can’t fix this.
\n\n[00:11:24] Portia asks Beth how she figures out what the reader needs from the documentation.
\n\n[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.
\n\n[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.
\n\n[00:30:23] Beth talks about teaching materials that Google publishes to help people with documentation.
\n\n[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.
\n\n[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.
\n\n[00:03:08] “Writing is not difficult and super scary and it’s easy for people to contribute.”
\n\n[00:05:43] “You can take a complex thing and you can clarify it, but you can’t reduce the complexity.”
\n\n[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.”
\n\n[00:10:01] “In the definition of done, the feature is done once it is documented and usable.”
\n\n[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.”
\n\n[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.”
\n\n[00:27:01] “Marketing is this whole other skillset that I do not have.”
\n\n[00:32:30] “At Google, there is a good culture of people caring about documentation and the tooling is good.”
\n\n[00:33:26] “I think having outdated documentation is slightly better, but not by much.”
\n\n[00:35:47] “A product manager recently told me it isn’t prioritization until it hurts.”
\n\nWho Writes the Docs?- with Beth Aitman (YouTube)
\n\n\n\nRiona MacNamara-As Good As It Gets: Why Better Trumps Best (YouTube)
\n\nA practical guide to making good documentation with Beth Aitman (HaskellerZ meetup)
\n\nessential Waitrose (HaskellerZ docs talks)
\n\nSpecial Guest: Beth Aitman.
Sponsored By:
Portia Burton | Eric Holscher
\n\nSwapnil Ogale
\n\nHello 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!
\n\n[00:00:56] Swapnil shares his story of how he got into technical writing.
\n\n[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.
\n\n[00:07:03] We learn what kind of value Swapnil gained from speaking at conferences and what the benefit is.
\n\n[00:10:26] Portia brings up how Swapnil advocates for himself and he explains the importance of this.
\n\n[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.
\n\n[00:15:16] Swapnil speaks at conferences about documentation, and he explains some of the reactions he gets after he gives these presentations.
\n\n[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.
\n\n[00:24:02] Swapnil explains what the global perspective is.
\n\n[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.
\n\n[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.
\n\n[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.”
\n\n[00:16:36] “So that’s that notion of ‘we didn’t know you could do that is what I’m trying to debunk.”
\n\n[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.”
\n\nGoogle Open Source Blog: Announcing Season of Docs 2022
\n\nAuslan (Australian Sign Language)
\n\nSpecial Guest: Swapnil Ogale.
Sponsored By:
Portia Burton | Eric Holscher
\n\nFabrizio Ferri-Benedetti
\n\nHello 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!
\n\n[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.
\n\n[00:06:55] We learn more about the Columbo Technique for technical writers.
\n\n[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.
\n\n[00:12:14] Fabrizio explains docs-as-code.
\n\n[00:17:28] We find out some skills Fabrizio picked up as a tech journalist that he still uses today.
\n\n[00:20:54] Fabrizio shares some advice if you’re interested in becoming a technical writer.
\n\n[00:25:46] We hear Fabrizio explain about improving the tool chain.
\n\n[00:31:31] Fabrizio talks about working on a children’s story on OpenTelemetry.
\n\n[00:34:40] Find out where you can follow Fabrizio online.
\n\n[00:03:57] “With the transition to tech writing, there’s something about precision in scientific language.”
\n\n[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.”
\n\n[00:13:59] “You can do docs-as-code with pretty much any markup language.”
\n\n[00:19:57] “It’s really hard to document something that doesn’t make sense.”
\n\n[00:21:14] “Some general tips I would say is to start building your own website which could also contain your own portfolio.”
\n\n[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.”
\n\nFabrizio Ferri-Benedetti Twitter
\n\nFabrizio Ferri-Benedetti LinkedIn
\n\n\n\nFabrizio Ferri-Benedetti GitHub
\n\n\n\n\n\n\n\nSpecial Guest: Fabrizio Ferri-Benedetti.
Sponsored By:
Portia Burton | Eric Holscher
\n\nTom Johnson
\n\nHello 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!
\n\n[00:01:02] Tom explains his API checklists and what prompted him to do it.
\n\n[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.
\n\n[00:07:17] Find out what the characteristics are of good “curb appeal” when it comes to developer documentation.
\n\n[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.
\n\n[00:15:11] Portia wonders the best way to interact with users if you are a small start-up.
\n\n[00:20:34] We learn about the feedback Tom got on his API checklist.
\n\n[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.
\n\n[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.
\n\n[00:36:50] We end with Tom sharing with us a series he’s currently working on.
\n\n[00:06:07] “It’s one of those things where you know it when you see it.”
\n\n[00:31:53] “There’s always things that are interesting to explore.”
\n\n[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.”
\n\nMeasuring documentation quality through user feedback
\n\n\n\nFive basketball strategies and how they might apply to tech comm
\n\nA hypothesis about influence on the web and the workplace
\n\nMy life story, or reflections on what shaped my life’s career trajectory
\n\nDocumenting APIs: A guide for technical writers and engineers
\n\nQuality checklist for API documentation
\n\nSpecial Guest: Tom Johnson.
Sponsored By:
Portia Burton | Eric Holscher
\n\nMegan Sullivan
\n\nHello 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!
\n\n[00:01:27] We hear what Megan did before specializing in technical documentation.
\n\n[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.
\n\n[00:10:44] Megan shares what inspired her to get into technical writing.
\n\n[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.
\n\n[00:16:51] Find out what inspired Megan to publish her manual and share it.
\n\n[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.
\n\n[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.
\n\n[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.
\n\n[00:32:25] We end with some shout-outs and cool things happening that you should check out.
\n\n[00:07:40] “There are a lot of different ways that knowing how to code can help you in different industries.”
\n\n[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.”
\n\n[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.”
\n\n[00:23:42] “I think a good way to get people to take documentation seriously is to talk about what’s hard about documentation.”
\n\nPersonal User Manual-Megan Sullivan
\n\n\n\nGatsbyCamp Fall-Docs for Everyone-Megan Sullivan (YouTube)
\n\nThe Secret History of Women in Coding (The New York Times Magazine)
\n\nDocs for Developers: An Engineer’s Field Guide to Technical Writing
\n\n\n\n\n\nSpecial Guest: Megan Sullivan.
Sponsored By:
","summary":"Megan Sullivan 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.","date_published":"2022-02-22T21:00:00.000-05:00","attachments":[{"url":"https://chrt.fm/track/28DGC9/aphid.fireside.fm/d/1437767933/98ecf3aa-9157-4278-a770-0bae0b9b7d99/f2791b03-4157-4f9a-8c1b-f3f132e47d96.mp3","mime_type":"audio/mpeg","size_in_bytes":67518415,"duration_in_seconds":2109}]}]}