Added more detail to "Why this way?" (#5171)

* Added more detail to "Why this way?"

Moved and updated the "Why this way?" section of the handbook.
This is related to https://github.com/fleetdm/fleet/issues/4821 .

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

* Update handbook/company.md

Co-authored-by: Mike Thomas <78363703+mike-j-thomas@users.noreply.github.com>

handbook/company.md

@@ -22,66 +22,6 @@ Fleet Device Management Inc. is an all-remote company, with team members spread
 The majority of the code, documentation, and content we create at Fleet is public and source-available. We strive to be open and transparent in the way we run the business; as much as confidentiality agreements (and time) allow. We perform better with an audience, and our audience performs better with us.
 
 
-## Why this way?
-
-### Why do we use a wireframe-first approach?
-Wireframing (or "drafting," as we often refer to it at Fleet) provides a clear overview of page layout, information architecture, user flow, and functionality. The wireframe-first approach extends beyond what users see on their screens. Wireframe-first is also excellent for drafting APIs, config settings, CLI options, and even business processes. 
-
-He's why we use a wireframe-first approach at Fleet.
-
-- We create a wireframe for every change we make and favor small, iterative changes to deliver value quickly. 
-- We can think through the functionality and user experience more deeply by wireframing before committing any code. As a result, our coding decisions are clearer, and our code is cleaner and easier to maintain.
-- Content hierarchy, messaging, error states, interactions, URLs, API parameters, and API response data are all considered during the wireframing process (often with several rounds of review). This initial quality assurance means engineers can focus on their code and confidently catch any potential edge-cases or issues along the way.
-- Wireframing is accessible to people who understand our users but are not necessarily code-literate. So anyone can contribute a suggestion (at any level of fidelity). At the very least, you'll need a napkin and a pen, although we prefer to use Figma.
-- With Figma, thanks to its powerful component and auto-layout features, we can create high-fidelity wireframes - fast. We can iterate quickly without costing more work and less [sunk-cost fallacy](https://dictionary.cambridge.org/dictionary/english/sunk-cost-fallacy).
-
-### Why mono repo?
-- One repo keeps all of the relevant work in one place. The only exception is when we're working on something confidential.
-- One repo means that there is less to get lost.
-- One repo pools GitHub stars to reflect Fleet’s actual presence better.
-
-### Why organize work in team-based kanban boards?
-- Kanban boards provide a uniform layout across all teams where anyone in the company can look to see what other teams are working on and have coming up.
-- The different columns on the boards allow us to create a game plan for our to-do list for each 3-week iteration.
-- These boards allow anyone in the world to contribute.
-
-### Why 3-week cadence?
-- Fleet product is released every 3 weeks, so everyone in the company is synced up to this same schedule.
-- Other companies use a 4-week release cycle, but at Fleet, we like to move a little faster to get more done.
-- Everyone knows when the new release is, so they also know when their work is due.
-
-### Why agile?
-- See [the agile manifesto](https://agilemanifesto.org/).
-- Collaborating and pushing for the next release creates the best product and culture.
-
-### Why the emphasis on training?
-- Investing in people makes them better and faster contributors.
-- Creating a culture of helping others results in people feeling more comfortable and confident even if they aren’t familiar with osquery.
-- A sharp focus on training means things are written down.
-
-### Why handbook-first strategy?
-- Watch [this video about the handbook-first strategy](https://www.youtube.com/watch?v=aZrK8AQM8Ro).
-- For more details, see [GitLab’s handbook-first strategy](https://about.gitlab.com/company/culture/all-remote/handbook-first-documentation/).
-- Documenting in the handbook allows Fleet to scale up and retain knowledge for consistency.
-
-### Why not continuously generate REST API reference docs from javadoc-style code comments?
-- Using Markdown allows anyone to edit Fleet's docs.
-- Generated docs become just as out of date as handmade docs, except since they are generated, they can become more difficult to edit and therefore gated/siloed.
-- Keeping the source of truth in code files confers less visibility/ accessibility/ modifiability for people without Golang coding experience.
-- Code comments are more difficult to locate and edit than a single Markdown file.
-- Autogenerating docs from code is not the only way to make sure reference docs accurately reflect the API.
-- As the Fleet REST API, documentation, and tools mature, a more declarative format such as OpenAPI might become the source of truth, but only after investing in a format and processes to make it visible, accessible, and modifiable for all contributors.
-
-### Why direct responsibility?
-We use the concept of [directly responsible individuals](https://fleetdm.com/handbook/people#directly-responsible-individuals) (DRIs) to know who is responsible for what.  Every group maintains its own dedicated [handbook page](https://fleetdm.com/handbook), which is kept up to date with accurate, current information, including the group's [kanban board](https://github.com/orgs/fleetdm/projects?type=beta), Slack channels, and recurring tasks ("rituals").
-
-#### Why group Slack channels?
-Groups are organized around goals.  Connecting people with the same goals helps them produce better results by fostering freer communication.  While groups sometimes align with the organization chart, some groups consist of people who do not report to the same manager.    For example, [product groups](https://fleetdm.com/handbook/product) like `#g-agent` include engineers too, not just the product manager.
-
-Every group at Fleet maintains specific Slack channels, which all group members join and keep unmuted.  Everyone else at Fleet is encouraged to mute these channels, using them only as needed.  Each channel has a directly responsible individual responsible for keeping up with all new messages, even if they aren't explicitly mentioned (`@`).
-
-
-
 ## 🌈 Values
 
 Fleet's values are a set of five ideals adopted by everyone on the team.  They describe the culture we are working together to deliver, inside and outside the company:
@@ -247,6 +187,79 @@ Between overthinking and rushing, there is a [golden mean](https://en.wikipedia.
   - [Open source is forever](https://twitter.com/mikermcneil/status/1476799587423772674).
 - Better your collaboration.
 
+## Why this way?
+
+### Why do we use a wireframe-first approach?
+Wireframing (or "drafting," as we often refer to it at Fleet) provides a clear overview of page layout, information architecture, user flow, and functionality. The wireframe-first approach extends beyond what users see on their screens. Wireframe-first is also excellent for drafting APIs, config settings, CLI options, and even business processes. 
+
+He's why we use a wireframe-first approach at Fleet.
+
+- We create a wireframe for every change we make and favor small, iterative changes to deliver value quickly. 
+- We can think through the functionality and user experience more deeply by wireframing before committing any code. As a result, our coding decisions are clearer, and our code is cleaner and easier to maintain.
+- Content hierarchy, messaging, error states, interactions, URLs, API parameters, and API response data are all considered during the wireframing process (often with several rounds of review). This initial quality assurance means engineers can focus on their code and confidently catch any potential edge-cases or issues along the way.
+- Wireframing is accessible to people who understand our users but are not necessarily code-literate. So anyone can contribute a suggestion (at any level of fidelity). At the very least, you'll need a napkin and a pen, although we prefer to use Figma.
+- With Figma, thanks to its powerful component and auto-layout features, we can create high-fidelity wireframes - fast. We can iterate quickly without costing more work and less [sunk-cost fallacy](https://dictionary.cambridge.org/dictionary/english/sunk-cost-fallacy).
+
+### Why do we use one repo?
+At Fleet, we keep everything in one repo. The only exception is when we're working on something confidential since GitHub does not allow confidential issues inside public repos. Here's why:
+
+- One repo is easier to manage. It has less surface area for keeping content up to date and reduces the risk of things getting lost and forgotten.
+- Our work is more visible and accessible to the community when all project pieces are available in one repo. 
+- One repo pools GitHub stars and more accurately reflects Fleet’s presence.
+- One repo means one set of automations and labels to manage. Resulting in a consistent GitHub experience that is easier to keep organized.
+
+
+### Why organize work in team-based kanban boards?
+It's helpful to have a consistent framework for how every team works, plans, and requests things from each other. Fleet's kanban boards are that framework, and they cover three goals:
+
+1. **Intake:** Give people from anywhere in the world the ability to request something from a particular team (i.e., add it to their backlog).
+2. **Planning:** Give the team's manager and other team members a way to plan the next three-week iteration of what the team is working on in a world (the board) where the team has ownership and feels confident making changes.
+3. **Shared to-do list:** What should I work on next? Who needs help? What important work is blocked? Is that bug fix merged yet? When will it be released? When will that new feature ship? What did I do yesterday?
+
+
+### Why a three-week cadence?
+The Fleet product is released every three weeks. By syncing the whole company to this schedule, we can:
+
+- keep all team members (especially those who aren't directly involved with the core product) aware of the current version of Fleet and when the next release is shipping.
+- align project planning and milestones across all teams, which helps us schedule our content calendar and manage company-wide goals.
+
+
+### Why use agile methodology?
+Releasing software iteratively gets changes and improvements into the hands of users faster and generally results in software that works. This makes contributors fitter, happier, and more productive. See [the agile manifesto](https://agilemanifesto.org/). for more information.
+
+
+### 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 make better decisions at work and to feel confident while doing so. 
+- create a culture of helping others, which results in team members feeling more comfortable even if they aren’t familiar with the osquery, security, startup, or IT space. 
+
+
+### Why not continuously generate REST API reference docs from javadoc-style code comments?
+We prefer to generate our REST API reference docs the good old-fashioned way. By hand. Here are a few of the drawbacks that we have experienced when generating docs via tools like Swagger or OpenAPI and some plus ones for doing it by hand with Markdown.
+
+- Markdown gives us more control over how the docs are compiled, what annotations we can include, and how we present the information to the end-user. 
+- Markdown is more accessible. Anyone can edit Fleet's docs directly from our website without needing coding experience. 
+- A single Markdown file reduces surface area sprawl that comes from spreading code comments across multiple files throughout the codebase. (see ["Why do we use one repo?"](why-do-we-use-one-repo)). 
+- Generated docs can become just as outdated as handmade docs, except since they are generated, they become siloed and more difficult to edit.
+- Autogenerated docs are typically hosted on a subdomain. This means we have less control over a user's journey through our website and lose the SEO benefits of self-hosted documentation.
+- Autogenerating docs from code is not always the best way to make sure reference docs accurately reflect the API. Based on our experience from past projects, we've learned that the benefits of generated docs do not outweigh the drawbacks of creating them by hand.
+- As the Fleet REST API, documentation, and tools mature, a more declarative format such as OpenAPI might become the source of truth, but only after investing in a format and processes to make it visible, accessible, and modifiable for all contributors.
+
+
+### Why handbook-first strategy?
+The Fleet handbook provides team members with up-to-date information about how to do things in the company. By adopting the handbook-first strategy, we can encourage a culture of self-service and self-learning, which is essential for daily a-synchronous work as part of an all-remote team.
+
+This strategy was inspired by GitHub, who use it to great effect. Check out this [short three-minute video](https://www.youtube.com/watch?v=aZrK8AQM8Ro) about their take on the handbook-first approach.
+
+
+
+### Why direct responsibility?
+We use the concept of [directly responsible individuals](https://fleetdm.com/handbook/people#directly-responsible-individuals) (DRIs) to know who is responsible for what. Every group maintains its own dedicated [handbook page](https://fleetdm.com/handbook), which is kept up to date with accurate, current information, including the group's [kanban board](https://github.com/orgs/fleetdm/projects?type=beta), Slack channels, and recurring tasks ("rituals").
+
+### Why group Slack channels?
+Groups are organized around goals. Connecting people with the same goals helps them produce better results by fostering freer communication. While groups sometimes align with the organization chart, some groups consist of people who do not report to the same manager. For example, [product groups](https://fleetdm.com/handbook/product) like `#g-agent` include engineers, not just the product manager.
+
+Every group at Fleet maintains specific Slack channels, which all group members join and keep unmuted.  Everyone else at Fleet is encouraged to mute these channels, using them only as needed.  Each channel has a directly responsible individual responsible for keeping up with all new messages, even if they aren't explicitly mentioned (`@`).
 
 
 ## History