Handbook/company/why-this-way/why-read-documentation (#12736)

Co-authored-by: Mike McNeil <mikermcneil@users.noreply.github.com>

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.