A Discourse on Documentation with Sam Brandt and Natalia Tepluhina

About our guests:

Natalia Tepluhina

• Twitter @N_Tepluhina
• Website

Sam Brandt

• Instagram @mxsambrandt
• Website

Welcome to Enjoy the Vue! Today we have two guest panelists with us, Sam Brandt and Natalia Tepluhina. Sam is a technical writer for Haven Life and Natalia is a Vue.js core team member and a Staff Frontend Engineer at GitLab. We will discuss good documentation and writing technical documentation specifically for Vue. Why is documentation so important? There is some great advice given by the panelists throughout the episode about things they don’t like about documentation, mistakes they’ve made, and things they learned, and some pet peeves they’ve encountered. Why are style guides so useful in documentation? Download this episode to find out all this and much more!

Outline

[00:01:15] Sam and Natalia give us a little background of themselves.

[00:03:21] There a lot of different kinds of documentation, so a few of the panelists tell us how they were drawn to write documentation and why it’s so important.

[00:18:03] We will talk about things that the panelists don’t like about documentation. So, we learn some mistakes they’ve made and regretted, and things they used to do that they’ve since learned this is a much better doing it this other way. Some great advice is given here. ☺

[00:28:14] Ari and Tessa tell us some of their pet peeves when it comes to encountering documentation.

[00:32:38] Sam talks about style guides being useful in documentation. Natalia tells us her favorite rules from their internal style guide.

[00:39:35] Ari tells us what of her greatest pet peeves when Chris talks about use cases, and then asks him how you land on the right amount of detail in a use case example.

[00:47:32] Tessa wants to know how to keep docs up to date, how to manage the really simple specific idea, and how to guide people between that liminal space.

[00:52:48] Speaking of automation, Chris tells us something he’s done in a pre-commit hook for project documentation and Natalia and Ben have something to add as well.

[00:56:50 ] Tessa asks what are some good practical tips that she can apply to a document more effectively and be advocate for documentation in a company. Great advice is given here by the panelists. ☺

[01:07:41] Natalia and Sam tell us where you can find them on the internet. Also, if you’re looking for a job as a technical writer, Sam gives a plug for their good friend who has a technical writing consulting business, called Good Words (link below).

Sam's picks:

• The City We Became by N.K. Jemisin
• The Okra Project
• The Old Guard - Netflix

Natalia's picks:

• Vue CLI 4.5
• Taylor Swift - folklore

Other resources mentioned:

• NaNoWriMo
• Good Words LLC