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.”