34 min
Mike Jang Let's Talk Docs
-
- Technology
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
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
34 min