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