we strongly recommend you write best practices
TRANSCRIPT
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.
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!
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