Episode 30: A Discourse on Documentation with Sam Brandt and Natalia Tepluhina
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!
Sponsored By:
Show Notes
[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 her good friend who has a technical writing consulting business, called Good Words (link below).
Picks of the week:
[01:08:53] Tessa has four picks: Shadazzle, Dr. Tung’s Ionic Toothbrush, Sänger Hot Water Bottle, and a book, On Writing Well, by William Zinsser.
[01:10:24] Ari has two picks: Cypress.io and singer, Donny Benét.
[01:12:14] Ben has three picks: A show on Netflix called, TWogether, Starship Command Prompt, and Nerd Fonts.
[01:14:13] Natalia has two picks: Vue CLI 4.5 and Taylor Swift’s folklore album (Spotify).
[01:15:46] Chris has three picks: Taylor Swift’s folklore album, two songs: Exile and My Tears Ricochet, OXO Good Grips Easy-Clean Compost Bin, and G Ganen Foldable Bathtub.
[01:17:40] Sam has three picks: A book, The City We Became by N.K. Jemisin, The Okra Project, and The Old Guard on Netflix.
Sponsor:
Honeybadger
Resources mentioned:
Natalia Tepluhina Website
Natalia Tepluhina Twitter
Sam Brandt Website
Sam Brandt Twitter
Sam Brandt Instagram
NaNoWriMo
Good Words LLC
Shadazzle
Dr. Tung's ionic toothbrush
Sänger Hot Water Bottle
On Writing Well by William Zinsser
Cypress.io
Donny Benét
TWogether-Netflix
Starship Command Prompt
Nerd Fonts
Vue CLI 4.5
Taylor Swift- folklore
OXO Good Grips Easy-Clean Compost
G Ganen Foldable Bathtub
The City We Became by N.K. Jemisin
The Okra Project
The Old Guard-Netflix
Special Guests: Natalia Tepluhina and Sam Brandt.