diff --git a/handbook/company/why-this-way.md b/handbook/company/why-this-way.md index d9dcb88cee..6fefa673af 100644 --- a/handbook/company/why-this-way.md +++ b/handbook/company/why-this-way.md @@ -41,6 +41,54 @@ Making changes to the handbook first [encourages](https://www.youtube.com/watch? To contribute to the handbook, click "Edit this page" and make your [edits in Markdown](https://fleetdm.com/handbook/company). +## Why read documentation? + +The three main things people are searching for are: + +### 🐋 "Tire-kicking" + +>I think this is cool, now is it something that I could ACTUALLY use? Does it ACTUALLY work? What all's in it? + + _**This is where I want to be sold!**_ + +>I want to have resources. _**Shiney new toys**_ đŸ•šī¸ to show my boss. Links I can share with colleagues to get them excited. + +### 📚 "Committed learning" + +>I've decided to learn this. I need a curriculum to get me there. Content that makes it as easy as possible, surface-level as possible. This is where I want to learn how it works and how to do things. + +### 🧭 "Quick reference" + + >Is this thing broken or am I using it right? How do I use this? Maybe they just stumbbled in from Google, an on-site search, or through Fleet nav itself. + + Quick refrence needs are especially relevant for: +- REST API pages +- The config surface of Fleet itself +- Agent options +- How to build YAML for fleetctl apply +- The built-in MDM profiles +- The table schema +- Query library with built-in policies +- Use cases like pulling up the reference architectures and AWS cost calculators + +## 🔌đŸšĒđŸĒŸ Principles + +### đŸšĒ Little tiny white lies + +Think of an iceberg . _**Looks**_ like smooth sailing, always. Happy path up top, hide the tricky bits underneath. Like math teachers don't even touch long division until long after you've learned fractions. +This is why the most complex stuff is always on the bottom of each page or section. + +It's ok if the sentences above the fold are overly simplified. + +Get to the _**SIMPLE, CLEAR**_ instructions first. Ideally a short example. Be prescriptive, brief, and clear. You can always hedge and caveat further down the page. + +- Example: Notice how this page gets more complicated as you scroll down:https://sailsjs.com/documentation/reference/blueprint-api/destroy + +- Another one: See how it starts off dead simple? (And then the caveats are below)https://sailsjs.com/documentation/concepts/models-and-orm/model-settings#?seldomused-settings + +- Good example in sails.js: https://sailsjs.com/documentation/concepts/models-and-orm/model-settings#?schema + + ## Why the emphasis on training? Investing in people and providing generous, prioritized training, especially up front, helps contributors understand what is going on at Fleet. By making training a prerequisite at Fleet, we can: - help team members feel confident in the better decisions they make at work.