Embed Size (px)
Citation preview
May 2014
Lauren Rother/ Technical WriterPuppet Labs Inc.
We Strongly Recommend You Write Best Practices
ValuesWhat do you mean, "best practices"?
The challenge: Users have different needs, different environments, different workflows, and most importantly, different levels of experience.The experiment: Beginner's Guide to Modules
ValuesFirst Iteration: All the things!
In the first version of the BGtM, we took inspiration from textbooks.
The Problem: Overwhelming
Hard to approach, first section is disproportionately huge.
The Lesson: Orientation
"Today, we will be learning about science!"
ValuesSecond Iteration: Introductions
Our second time around, we added headings and short introductory paragraphs.
Mantra
It's hard to locate distinct items. You can't really come back to the document.
The Problem: Hard to navigate
The Lesson (Part 1): Guide, don't impart
You Kant give a Groundwork, you must give a guidebook.
The Lesson (Part 2): Step-by-step
I should've listened to New Kids on the Block. It's all about the steps.
ValuesFinal Iteration: Intros and steps
The final version has a table of contents, headings, steps, introductory sentences, and examples!
Mantra
Not enough get-your-hands-dirty details.
The Problem: Too high-level
The Lesson: Logic
You can have your Kant and read it, too!
ValuesNext steps
● Working on the Advanced Guide to Modules:○ moar logic, moar pages○ building a module in the doc, linked to GitHub with
branches for each section
http://docs.puppetlabs.com/guides/module_guides/bgtm.html
ValuesBest Practices link
RFC language guide:http://www.faqs.org/rfcs/rfc2119.html
