Only quick reference docs (#19388)

Co-authored-by: Rachael Shaw <r@rachael.wtf>
Co-authored-by: Mike McNeil <mikermcneil@users.noreply.github.com>
This commit is contained in:
Noah Talerman 2024-06-03 14:01:46 -04:00 committed by GitHub
parent 2db2b4ede1
commit 7f8027a92c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -48,6 +48,8 @@ There are three reasons for visiting [the docs](https://fleetdm.com/docs):
- **Committed learning**: "I've decided to learn this. I need a curriculum to get me there; with content that makes it as easy as possible, surface-level as possible. I want to learn how Fleet works and how to do all the things."
- **Quick reference**: "Is this thing broken or am I using it right? How do I use this?" Whether they just stumbled in from a search engine, an on-site search, or through the Fleet website navigation, visitors interested in quick reference are interested in getting to the correct answer quickly. Quick referencers search for REST API pages, the config surface of the Fleet server, agent options, how to build YAML for `fleetctl apply`, the built-in MDM profiles, the table schema, the built-in queries, reference architectures and cost calculators for deploying your own Fleet instance.
> Currently, Fleet only adds new "Quick reference" content to the [docs](fleetdm.com/docs). New "Committed learning" docs should be written as [articles](https://fleetdm.com/articles). Why? The docs surface area is large and Fleet iterates on features more quickly than we can update extensive how-tos. We've learned that users are more forgiving when articles are out-of-date. But, reference documentation always needs to be correct.
Everyone [can contribute](https://fleetdm.com/handbook/company#openness) to Fleet's documentation. Here are a few principles to keep in mind:
- **🚪 Start simple.** It's easier to learn when you aren't overwhelmed. Good documentation pages and sections start _prescriptive, brief, and clear_; ideally with a short example. You can always hedge and caveat further down the page. This makes the docs more [accessible and outsider-friendly](https://fleetdm.com/handbook/company#purpose). For example, notice how [this page gets more complicated as you scroll down](https://sailsjs.com/documentation/reference/blueprint-api/destroy), or how [both](https://sailsjs.com/documentation/concepts/models-and-orm/model-settings#?schema) of [these sections](https://sailsjs.com/documentation/concepts/models-and-orm/model-settings#?seldomused-settings) start simple, with caveats pushed down to the end.