mirror of
https://github.com/fleetdm/fleet
synced 2026-05-23 00:49:03 +00:00
Charlie company handbook patch (#7791)
* Create why-this-way.md Moved "Why this way" to it's own page within Company handbook. * Create development-groups.md Added new page development-groups.md to Company handbook. * Update README.md Added space for Charlie to write summary for our new sections and add links to the nested pages. * Update development-groups.md Added meta tags to the page. * Update why-this-way.md * Update why-this-way.md Changed head hierarchy to populate sub nav. * preamble and links to sub pages Co-authored-by: Mike Thomas <78363703+mike-j-thomas@users.noreply.github.com>
This commit is contained in:
Charlie Chance
GitHub
parent
ba339a2a0a
commit
1a781fca6f
3 changed files with 219 additions and 216 deletions
|
|
@ -184,222 +184,6 @@ Between overthinking and rushing, there is a [golden mean](https://en.wikipedia.
|
|||
- Declassify with care (easier to overlook confidential info when declassifying vs. when changing something that is already public from the get-go).
|
||||
- [Open source is forever](https://twitter.com/mikermcneil/status/1476799587423772674).
|
||||
|
||||
## 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.
|
||||
|
||||
Here'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.
|
||||
- Designing from the "outside, in" gives us the opportunity to obsess over details in the interaction design. An undefined "what" exposes the results to the chaos of unplanned extra work and context shifting for engineers. This way, every engineer doesn't have to personally spend the time to get and stay up to speed with:
|
||||
- the latest reactions from users
|
||||
- all of the motivations and discussions from the previous rounds of wireframe revisions that were thrown away
|
||||
- how the UI has evolved in previous releases to better serve the people using and building it
|
||||
- Wireframing is important for both maintaining the quality of our work and outlining what work needs to be done.
|
||||
- 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 feel confident in the better decisions they make at work.
|
||||
- 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?
|
||||
Here are a few of the drawbacks that we have experienced when generating docs via tools like Swagger or OpenAPI, and some of the advantages of 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 the amount of surface area to manage 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)).
|
||||
- Autogenerated docs can become just as outdated as handmade docs, except since they are siloed, they require more skills to edit.
|
||||
- When docs live at separate repo paths from source code, we are able to automate approval processes that allow contributors to make small improvements and notes, directly from the website. This [leads to more contributions](https://github.com/balderdashy/sails-docs/network/members), since it lowers the barrier of entry for [becoming a contributor](https://fleetdm.com/docs/contributing/committing-changes).
|
||||
- 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 comments is not always the best 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 continually accurate as well as 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 GitLab, which uses it with 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 (`@`).
|
||||
|
||||
|
||||
## Development groups
|
||||
|
||||
Fleet organizes development groups by their goals. These include members from Design, Engineering, and Product.
|
||||
|
||||
Goals:
|
||||
|
||||
_progress (+) guarantee_
|
||||
|
||||
- **Interface** - more, successfully adopted features faster
|
||||
- (+) keep UI & API simple, minimalist, consistent, and bug-free
|
||||
- **Platform** - improve the productivity of the Interface team through patterns and infrastructure for implementing new features, reduce REST API latency, increase max load test size, make upgrading seamless for users, improve accuracy and reliability of data
|
||||
- (+) maintain quick time-til-merge timeframe for PRs reviewed, and maintain clean, empathetic interfaces that allow contributors in other groups to execute quickly and without the need to wait for review or approvals
|
||||
- **Agent**: grow # open source, osquery-based agents by making Fleet’s agents better, faster, and broader in capabilities
|
||||
- (+) every table works intuitively with user-friendly docs and empathetic caveats, warnings, and error messages
|
||||
|
||||
At Fleet, groups define the relevant sections of the engineering org chart. A product manager (PM) represents each group and reports to the Product department (or a founder serving as an
|
||||
interim product manager):
|
||||
|
||||
- Interface PM: Noah Talerman
|
||||
- Platform PM: Mo Zhu
|
||||
- Agent PM: Mo Zhu
|
||||
|
||||
Each group's PM works closely with engineers within their group:
|
||||
- The PM **prioritizes** work and defines **what** to iteratively build and release next within their group's domain to best serve the group's goals and the company's goals as a whole. The PM communicates **why** this work is prioritized and works with engineering to come up with the best possible **how**.
|
||||
- The PM is responsible for the execution of initiatives (epics) that span across multiple groups. These epics are tracked as GitHub issues with the "epic" label. One PM is assigned to the epic to make sure that all issues associated with the epic (child issues) make it into a release.
|
||||
|
||||
An engineering manager (EM), with their group of engineers, forms the engineering members of the group:
|
||||
|
||||
- Interface EM: Luke Heath
|
||||
- Platform EM: Tomás Touceda
|
||||
- Agent EM: Zach Wasserman
|
||||
|
||||
Each group's EM works closely with the PM and engineers in their group:
|
||||
- The EM (along with engineers) defines **how** to implement that definition within the surface area of code, processes, and rituals owned by their group while serving their group’s goals and the company's goals as a whole.
|
||||
- The EM is responsible for the execution of epics within their group. One EM is assigned to the epic to make sure that all child issues make it into a release.
|
||||
|
||||
### Interface group
|
||||
#### Responsibilities
|
||||
- Everything related to Fleet's graphical user interface (other than for the desktop application portion of Fleet Desktop)
|
||||
- `fleetctl` (the Fleet command-line interface) and the associated YAML documents (almost everything in fleetctl besides the `fleetctl debug` subcommands)
|
||||
- The REST API that serves these
|
||||
- The UX/developer experience, flow, steps, and associated UI and API interfaces for how integrations that require any user interaction or configuration (e.g., GeoIP, Zendesk, Jira), including which third-party integrations are supported and which API styles and versions are chosen
|
||||
- End to end testing of the application (e.g., Cypress)
|
||||
- The REST API documentation
|
||||
- Future officially-supported wrapper SDKs, such as the Postman collection or, e.g., a Python SDK
|
||||
- Fleet's configuration surface, including
|
||||
- The config settings that exist for Fleet deployments and how they're configured
|
||||
- How feature flags are used
|
||||
- Their default values, supported data types, and error messages
|
||||
- Associated documentation on fleetdm.com
|
||||
- The UX of upgrading and downgrading and sidegrading Fleet tiers, and managing license keys
|
||||
|
||||
#### Consumers
|
||||
- A human using Fleet's graphical user interface
|
||||
- A human who is writing code that integrates Fleet's REST API
|
||||
- A human reading Fleet's REST API docs
|
||||
- A human using fleetctl, Fleet's Postman collection or Fleet's other future SDK wrappers
|
||||
|
||||
These humans might be working within the "Interface" group itself insofar as they consume the Fleet REST API. Or they might be a contributor to the Fleet community. Or one of Fleet's core users or customers, usually in an SRE, IT, or security role in an organization.
|
||||
|
||||
#### Goals
|
||||
- Bring value to Fleet users by delivering new features and iterations of existing features.
|
||||
- Increase adoption and stickiness of features.
|
||||
- Keep the graphical user interface, REST API, fleetctl, and SDKs like Postman reliable, minimal, consistent, and easy to use.
|
||||
- Promote stability of the API, introducing breaking changes only through the documented [API versioning](https://fleetdm.com/docs/contributing/api-versioning#what-kind-of-versioning-will-we-use-for-the-api) strategy or at major version releases.
|
||||
- Ensure observance of semantic versioning for the Fleet API and config between releases so that only major versions include breaking changes.
|
||||
- Delight users of Fleet's API, UI, SDKs, and documentation with a simple, secure, widely-adopted user and developer experience.
|
||||
- **Improve Fleet’s feature value and ease of use.**
|
||||
|
||||
### Platform group
|
||||
#### Responsibilities
|
||||
- The implementation of Fleet Agent API: i.e.,
|
||||
- The API used by agents on enrolled hosts to communicate with Fleet
|
||||
- The API used by agents for doing auto-updates and future installation/upgrade of custom extensions (e.g., TUF)
|
||||
- Everything related to providing a stable, simple-to-build-on platform for Fleet contributors to use when implementing changes to the REST API
|
||||
- APIs for storing, retrieving, and modifying device data
|
||||
- APIs for running asynchronous and scheduled tasks
|
||||
- APIs for communicating with external services (e.g., HTTP, SMTP)
|
||||
- The challenges of scale
|
||||
- Sometimes taking over development/improvement of features from the “Interface” group when these features have unexpected backend complexity or scaling challenges.
|
||||
- Production infrastructure, including
|
||||
- Fleet Cloud demo
|
||||
- Fleet Cloud prod
|
||||
- The registry (TUF) used for auto-updates and (in the future) extensions
|
||||
- whatever backend is needed to generate installers in self-managed and hosted Fleet deployments
|
||||
- The future monitoring and 24/7/365 enhancement to the on-call rotation necessary for Fleet Cloud
|
||||
- Behind-the-scenes integrations
|
||||
- i.e., integrations that make Fleet "just work" and don't involve configuration from users
|
||||
- Example: the code that fetches and manages CVE data from NVD and other behind-the-scenes infrastructure that enables vulnerability management to exist in Fleet without requiring any interactions or configuration from users
|
||||
- The CI/CD pipeline
|
||||
- `loadtest.fleetdm.com`
|
||||
- `dogfood.fleetdm.com`
|
||||
|
||||
#### Consumers
|
||||
- A contributor from inside or outside the company.
|
||||
- A host enrolled in Fleet running an osquery-based agent.
|
||||
- The person who deploys, upgrades, and operates Fleet.
|
||||
- A person who uses Fleet and expects it to be fast, reliable, and joyful.
|
||||
|
||||
#### Goals
|
||||
- Reduce REST API latency
|
||||
- Increase max load test size
|
||||
- Reduce infrastructure costs for Fleet deployments.
|
||||
- Make upgrading Fleet versions seamless for users.
|
||||
- Improve the integrity of data (both collected directly from agents or derived from that data, e.g., vulnerabilities).
|
||||
- Maintain quick time-til-merge timeframe for PRs reviewed.
|
||||
- Maintain clean, empathetic interfaces that allow contributors in other groups (or from outside the company) to execute quickly and without the need to wait for review or approval.
|
||||
- **Make Fleet as easy as possible to operate and contribute to**
|
||||
|
||||
### Agent group
|
||||
#### Responsibilities
|
||||
- osquery core, including the plugin interfaces and its config surface.
|
||||
- Orbit
|
||||
- Fleet Desktop
|
||||
- Any future agent-based software built by Fleet.
|
||||
- Fleet Agent API: the API interface and contributor docs used by osquery-enrolled agents for communicating with Fleet (how to implement the internals is up to the "Platform" group).
|
||||
- The extensions/tables are bundled in Orbit/Fleet Desktop, such as mac admins.
|
||||
|
||||
#### Consumers
|
||||
- An engineer working on a custom solution (usually built in-house) on top of osquery
|
||||
- An SRE, IT operations, or DevOps professional using osquery-based agents in their default AMIs or container images, which deploys and manages osquery-based agents on their laptops, production servers/containers, and other corporate infrastructure
|
||||
- An end-user running an osquery-based agent (Fleet Desktop, orbit, or osquery) on their work laptop, who wants their laptop to be stable, performant, and as private as possible
|
||||
- An enterprise app owner (software engineer) running osquery-based agents on her app's servers
|
||||
- A contributor working on vanilla osquery in osquery/osquery
|
||||
- A contributor working on Fleet Desktop or orbit in fleetdm/fleet
|
||||
- Fleet itself, consuming the data generated by osquery and any other agent software
|
||||
|
||||
#### Goals
|
||||
- Grow mind/market share of open source, osquery-based agents by making Fleet’s agents better, faster, and broader in capabilities
|
||||
- Every table works intuitively with user-friendly docs and empathetic caveats, warnings, and error messages
|
||||
- Every table is documented within the Fleet UI and in fleetdm.com/docs, with GOTCHAS, deprecation notices, and the version when the table was added
|
||||
- **Make Fleet’s agents easy to operate and contribute to**
|
||||
|
||||
|
||||
## History
|
||||
|
||||
### 2014: Origins of osquery
|
||||
|
|
@ -414,6 +198,14 @@ When Kolide's attention shifted away from Fleet, and towards their separate, use
|
|||
### 2020: Fleet was incorporated
|
||||
Zach partnered with our CEO, Mike McNeil, to found a new, independent company: Fleet Device Management Inc. In November 2020, we [announced](https://medium.com/fleetdm/a-new-fleet-d4096c7de978) the transition and kicked off the logistics of moving the GitHub repository.
|
||||
|
||||
## Why this way?
|
||||
|
||||
Fleet has a unique way of organizing work. For more information, check out this page [Why this way](./why-this-way.md).
|
||||
|
||||
## Development groups
|
||||
|
||||
Fleet organizes development groups by their goals. These include members from Design, Engineering, and Product. For more information, check out this page [Development groups](./development-groups.md).
|
||||
|
||||
## Levels of confidentiality
|
||||
|
||||
- *Public* _(share with anyone, anywhere in the world)_
|
||||
|
|
|
|||
135
handbook/company/development-groups.md
Normal file
135
handbook/company/development-groups.md
Normal file
|
|
@ -0,0 +1,135 @@
|
|||
# Development groups
|
||||
|
||||
Fleet organizes development groups by their goals. These include members from Design, Engineering, and Product.
|
||||
|
||||
Goals:
|
||||
|
||||
_progress (+) guarantee_
|
||||
|
||||
- **Interface** - more, successfully adopted features faster
|
||||
- (+) keep UI & API simple, minimalist, consistent, and bug-free
|
||||
- **Platform** - improve the productivity of the Interface team through patterns and infrastructure for implementing new features, reduce REST API latency, increase max load test size, make upgrading seamless for users, improve accuracy and reliability of data
|
||||
- (+) maintain quick time-til-merge timeframe for PRs reviewed, and maintain clean, empathetic interfaces that allow contributors in other groups to execute quickly and without the need to wait for review or approvals
|
||||
- **Agent**: grow # open source, osquery-based agents by making Fleet’s agents better, faster, and broader in capabilities
|
||||
- (+) every table works intuitively with user-friendly docs and empathetic caveats, warnings, and error messages
|
||||
|
||||
At Fleet, groups define the relevant sections of the engineering org chart. A product manager (PM) represents each group and reports to the Product department (or a founder serving as an
|
||||
interim product manager):
|
||||
|
||||
- Interface PM: Noah Talerman
|
||||
- Platform PM: Mo Zhu
|
||||
- Agent PM: Mo Zhu
|
||||
|
||||
Each group's PM works closely with engineers within their group:
|
||||
- The PM **prioritizes** work and defines **what** to iteratively build and release next within their group's domain to best serve the group's goals and the company's goals as a whole. The PM communicates **why** this work is prioritized and works with engineering to come up with the best possible **how**.
|
||||
- The PM is responsible for the execution of initiatives (epics) that span across multiple groups. These epics are tracked as GitHub issues with the "epic" label. One PM is assigned to the epic to make sure that all issues associated with the epic (child issues) make it into a release.
|
||||
|
||||
An engineering manager (EM), with their group of engineers, forms the engineering members of the group:
|
||||
|
||||
- Interface EM: Luke Heath
|
||||
- Platform EM: Tomás Touceda
|
||||
- Agent EM: Zach Wasserman
|
||||
|
||||
Each group's EM works closely with the PM and engineers in their group:
|
||||
- The EM (along with engineers) defines **how** to implement that definition within the surface area of code, processes, and rituals owned by their group while serving their group’s goals and the company's goals as a whole.
|
||||
- The EM is responsible for the execution of epics within their group. One EM is assigned to the epic to make sure that all child issues make it into a release.
|
||||
|
||||
## Interface group
|
||||
### Responsibilities
|
||||
- Everything related to Fleet's graphical user interface (other than for the desktop application portion of Fleet Desktop)
|
||||
- `fleetctl` (the Fleet command-line interface) and the associated YAML documents (almost everything in fleetctl besides the `fleetctl debug` subcommands)
|
||||
- The REST API that serves these
|
||||
- The UX/developer experience, flow, steps, and associated UI and API interfaces for how integrations that require any user interaction or configuration (e.g., GeoIP, Zendesk, Jira), including which third-party integrations are supported and which API styles and versions are chosen
|
||||
- End to end testing of the application (e.g., Cypress)
|
||||
- The REST API documentation
|
||||
- Future officially-supported wrapper SDKs, such as the Postman collection or, e.g., a Python SDK
|
||||
- Fleet's configuration surface, including
|
||||
- The config settings that exist for Fleet deployments and how they're configured
|
||||
- How feature flags are used
|
||||
- Their default values, supported data types, and error messages
|
||||
- Associated documentation on fleetdm.com
|
||||
- The UX of upgrading and downgrading and sidegrading Fleet tiers, and managing license keys
|
||||
|
||||
### Consumers
|
||||
- A human using Fleet's graphical user interface
|
||||
- A human who is writing code that integrates Fleet's REST API
|
||||
- A human reading Fleet's REST API docs
|
||||
- A human using fleetctl, Fleet's Postman collection or Fleet's other future SDK wrappers
|
||||
|
||||
These humans might be working within the "Interface" group itself insofar as they consume the Fleet REST API. Or they might be a contributor to the Fleet community. Or one of Fleet's core users or customers, usually in an SRE, IT, or security role in an organization.
|
||||
|
||||
### Goals
|
||||
- Bring value to Fleet users by delivering new features and iterations of existing features.
|
||||
- Increase adoption and stickiness of features.
|
||||
- Keep the graphical user interface, REST API, fleetctl, and SDKs like Postman reliable, minimal, consistent, and easy to use.
|
||||
- Promote stability of the API, introducing breaking changes only through the documented [API versioning](https://fleetdm.com/docs/contributing/api-versioning#what-kind-of-versioning-will-we-use-for-the-api) strategy or at major version releases.
|
||||
- Ensure observance of semantic versioning for the Fleet API and config between releases so that only major versions include breaking changes.
|
||||
- Delight users of Fleet's API, UI, SDKs, and documentation with a simple, secure, widely-adopted user and developer experience.
|
||||
- **Improve Fleet’s feature value and ease of use.**
|
||||
|
||||
## Platform group
|
||||
### Responsibilities
|
||||
- The implementation of Fleet Agent API: i.e.,
|
||||
- The API used by agents on enrolled hosts to communicate with Fleet
|
||||
- The API used by agents for doing auto-updates and future installation/upgrade of custom extensions (e.g., TUF)
|
||||
- Everything related to providing a stable, simple-to-build-on platform for Fleet contributors to use when implementing changes to the REST API
|
||||
- APIs for storing, retrieving, and modifying device data
|
||||
- APIs for running asynchronous and scheduled tasks
|
||||
- APIs for communicating with external services (e.g., HTTP, SMTP)
|
||||
- The challenges of scale
|
||||
- Sometimes taking over development/improvement of features from the “Interface” group when these features have unexpected backend complexity or scaling challenges.
|
||||
- Production infrastructure, including
|
||||
- Fleet Cloud demo
|
||||
- Fleet Cloud prod
|
||||
- The registry (TUF) used for auto-updates and (in the future) extensions
|
||||
- whatever backend is needed to generate installers in self-managed and hosted Fleet deployments
|
||||
- The future monitoring and 24/7/365 enhancement to the on-call rotation necessary for Fleet Cloud
|
||||
- Behind-the-scenes integrations
|
||||
- i.e., integrations that make Fleet "just work" and don't involve configuration from users
|
||||
- Example: the code that fetches and manages CVE data from NVD and other behind-the-scenes infrastructure that enables vulnerability management to exist in Fleet without requiring any interactions or configuration from users
|
||||
- The CI/CD pipeline
|
||||
- `loadtest.fleetdm.com`
|
||||
- `dogfood.fleetdm.com`
|
||||
|
||||
### Consumers
|
||||
- A contributor from inside or outside the company.
|
||||
- A host enrolled in Fleet running an osquery-based agent.
|
||||
- The person who deploys, upgrades, and operates Fleet.
|
||||
- A person who uses Fleet and expects it to be fast, reliable, and joyful.
|
||||
|
||||
### Goals
|
||||
- Reduce REST API latency
|
||||
- Increase max load test size
|
||||
- Reduce infrastructure costs for Fleet deployments.
|
||||
- Make upgrading Fleet versions seamless for users.
|
||||
- Improve the integrity of data (both collected directly from agents or derived from that data, e.g., vulnerabilities).
|
||||
- Maintain quick time-til-merge timeframe for PRs reviewed.
|
||||
- Maintain clean, empathetic interfaces that allow contributors in other groups (or from outside the company) to execute quickly and without the need to wait for review or approval.
|
||||
- **Make Fleet as easy as possible to operate and contribute to**
|
||||
|
||||
## Agent group
|
||||
### Responsibilities
|
||||
- osquery core, including the plugin interfaces and its config surface.
|
||||
- Orbit
|
||||
- Fleet Desktop
|
||||
- Any future agent-based software built by Fleet.
|
||||
- Fleet Agent API: the API interface and contributor docs used by osquery-enrolled agents for communicating with Fleet (how to implement the internals is up to the "Platform" group).
|
||||
- The extensions/tables are bundled in Orbit/Fleet Desktop, such as mac admins.
|
||||
|
||||
### Consumers
|
||||
- An engineer working on a custom solution (usually built in-house) on top of osquery
|
||||
- An SRE, IT operations, or DevOps professional using osquery-based agents in their default AMIs or container images, which deploys and manages osquery-based agents on their laptops, production servers/containers, and other corporate infrastructure
|
||||
- An end-user running an osquery-based agent (Fleet Desktop, orbit, or osquery) on their work laptop, who wants their laptop to be stable, performant, and as private as possible
|
||||
- An enterprise app owner (software engineer) running osquery-based agents on her app's servers
|
||||
- A contributor working on vanilla osquery in osquery/osquery
|
||||
- A contributor working on Fleet Desktop or orbit in fleetdm/fleet
|
||||
- Fleet itself, consuming the data generated by osquery and any other agent software
|
||||
|
||||
### Goals
|
||||
- Grow mind/market share of open source, osquery-based agents by making Fleet’s agents better, faster, and broader in capabilities
|
||||
- Every table works intuitively with user-friendly docs and empathetic caveats, warnings, and error messages
|
||||
- Every table is documented within the Fleet UI and in fleetdm.com/docs, with GOTCHAS, deprecation notices, and the version when the table was added
|
||||
- **Make Fleet’s agents easy to operate and contribute to**
|
||||
|
||||
<meta name="maintainedBy" value="mikermcneil">
|
||||
<meta name="title" value="Development groups">
|
||||
76
handbook/company/why-this-way.md
Normal file
76
handbook/company/why-this-way.md
Normal file
|
|
@ -0,0 +1,76 @@
|
|||
# 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.
|
||||
|
||||
Here'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.
|
||||
- Designing from the "outside, in" gives us the opportunity to obsess over details in the interaction design. An undefined "what" exposes the results to the chaos of unplanned extra work and context shifting for engineers. This way, every engineer doesn't have to personally spend the time to get and stay up to speed with:
|
||||
- the latest reactions from users
|
||||
- all of the motivations and discussions from the previous rounds of wireframe revisions that were thrown away
|
||||
- how the UI has evolved in previous releases to better serve the people using and building it
|
||||
- Wireframing is important for both maintaining the quality of our work and outlining what work needs to be done.
|
||||
- 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 feel confident in the better decisions they make at work.
|
||||
- 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?
|
||||
Here are a few of the drawbacks that we have experienced when generating docs via tools like Swagger or OpenAPI, and some of the advantages of 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 the amount of surface area to manage 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)).
|
||||
- Autogenerated docs can become just as outdated as handmade docs, except since they are siloed, they require more skills to edit.
|
||||
- When docs live at separate repo paths from source code, we are able to automate approval processes that allow contributors to make small improvements and notes, directly from the website. This [leads to more contributions](https://github.com/balderdashy/sails-docs/network/members), since it lowers the barrier of entry for [becoming a contributor](https://fleetdm.com/docs/contributing/committing-changes).
|
||||
- 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 comments is not always the best 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 continually accurate as well as 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 GitLab, which uses it with 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 (`@`).
|
||||
|
||||
<meta name="maintainedBy" value="mikermcneil">
|
||||
<meta name="title" value="Why this way?">
|
||||
Loading…
Reference in a new issue