diff --git a/handbook/product.md b/handbook/product.md index ad71764f51..19473edb4a 100644 --- a/handbook/product.md +++ b/handbook/product.md @@ -6,7 +6,7 @@ ## Job to be done -Every product should have a single job that it strives to do. At Fleet, we use the [Jobs to be Done +Every product should have a single job that it strives to do. We use the [Jobs to be Done (JTBD) framework](https://about.gitlab.com/handbook/engineering/ux/jobs-to-be-done/). Fleet's overarching job to be done is the following: @@ -28,10 +28,10 @@ The following Q2 OKRs Google doc lists the "Product" sub-OKRs under each organiz ## Q1 2022 product objectives -In Q1 2022, Fleet set companywide objectives. The product team was responsible for +In Q1 2022, Fleet set company-wide objectives. The product team was responsible for the product objectives that contributed to the company-wide objectives. -The following list includes the company wide objectives, product objectives ("How?" sections), and whether or not the +The following list includes the company-wide objectives, product objectives ("How?" sections), and whether or not the product team hit or missed each objective: #### Ultimate source of truth @@ -45,7 +45,7 @@ in the UI and API. - Solve the "Undetermined" performance impact limitation for new scheduled queries as well as reflect unfinished policy runs in the UI/API (Miss). -- Only advertise working osquery tables inside the product by looking at you `wifi_networks` table +- Only advertise working osquery tables inside the product by looking at your `wifi_networks` table (Miss). #### Programmable @@ -56,9 +56,9 @@ device data in unique ways to their organization. ##### How? -- Add integrations for policy and vulnerability automations as well as get closer to parity with - other vulnerability management solutions(Miss). -- Roll up software and vulnerabilities across the entire organization and teams(Hit). +- Add integrations for policy and vulnerability automations (Miss). +- Take steps toward feature parity with other vulnerability management solutions (Miss). +- Roll up software and vulnerabilities across the entire organization and teams (Hit). #### Who's watching the watchers @@ -120,18 +120,18 @@ these changes to the engineering team. ### Deliver -* Once your work is complete and all feedback is addressed, ensure that the issue is updated with +* Once your work is complete and all feedback is addressed, make sure that the issue is updated with a link to the correct page in the Fleet EE (scratchpad) Figma. This page is where the design specifications live. -* Add the issue to the πŸ› Architect column in [the πŸ›Έ Product project](https://github.com/orgs/fleetdm/projects/27). This way, an architect on the engineering team knows that the issue is ready for engineering specifications and later, +* Add the issue to the πŸ› Architect column in [the πŸ›Έ Product project](https://github.com/orgs/fleetdm/projects/27). This way, an architect on the engineering team knows that the issue is ready for engineering specifications and, later, engineering estimation. #### Priority drafting Priority drafting is the revision of drafted changes currently being developed by the engineering team. Priority drafting aims to quickly adapt to unknown edge cases and -changing specification while ensuring +changing specifications while ensuring that Fleet meets our brand and quality guidelines. Priority drafting occurs in the following scenarios: @@ -140,11 +140,11 @@ Priority drafting occurs in the following scenarios: continuing the development task. * Functionality included in a drafted UI change must be cut down in order to ship the improvement in - the current scheduled release. + the currently scheduled release. What happens during priority drafting? -1. Everyone on the product and engineering teams is aware that a drafted change was brought back +1. Everyone on the product and engineering teams know that a drafted change was brought back to drafting and prioritized. 2. Drafts are updated to cover edge cases or reduce functionality. @@ -154,27 +154,27 @@ What happens during priority drafting? ## Planning -- The intake process for a given group (how new issues are received from a given requestor and estimated within the group's timeframe) is up to each group's PM. For example, the Interface group's intake process consists of attending Interface PM's office hours and making a case, at which time a decision about whether to draft and estimate will be made on the spot. +- The intake process for a given group (how new issues are received from a given requestor and estimated within the group's timeframe) is up to each group's PM. For example, the Interface group's intake process consists of attending Interface PM's office hours and making a case, at which time a decision about whether to draft an estimate will be made on the spot. - New unestimated issues are created in the Planning board, which is shared by each group. -- The estimation process to use is up to the EM of each group (with buy-in from the PM), with the goal of delivering estimated issues within the group's timeframe, which is set for each group by the Head of Product. No matter the group, only work that is slated to be released into the hands of users within ≀6 weeks will be estimated. Estimation is run by each group's EM, and occurs in the Planning board. Some groups may choose to use "timeboxes" rather than estimates. +- The estimation process to use is up to the EM of each group (with buy-in from the PM), with the goal of delivering estimated issues within the group's timeframe, which is set for each group by the Head of Product. No matter the group, only work that is slated to be released into the hands of users within ≀six weeks will be estimated. Estimation is run by each group's EM and occurs on the Planning board. Some groups may choose to use "timeboxes" rather than estimates. -- Prioritization will now occur at the point of intake, by the PM of the group. Besides the 20% "engineering initiatives", only issues prioritized by the group PM will be estimated or worked on. On the first day of each release, all estimated issues are moved into the relevant section of the new "Release" board, which has a kanban view per-group. +- Prioritization will now occur at the point of intake by the PM of the group. Besides the 20% "engineering initiatives," only issues prioritized by the group PM or worked on or estimated. On the first day of each release, all estimated issues are moved into the relevant section of the new "Release" board, which has a kanban view per group. -- Work that does not "fit" into the scheduled release (due to lack of capacity or otherwise) remains in the "Estimated" column of the product board, and is removed from that board if it is not prioritized in the following release. +- Work that does not "fit" into the scheduled release (due to lack of capacity or otherwise) remains in the "Estimated" column of the product board and is removed from that board if it is not prioritized in the following release. ### Process -1. **Intake:** Each group has a "time til estimated" timeframe, which measures the time from when an idea is first received until it is written up as an estimated issue and the requestor notified exactly which aspects are scheduled for release. How intake works, and the estimation timeframe, vary per group, but every group has an estimation timeframe. +1. **Intake:** Each group has a "time til estimated" timeframe, which measures the time from when an idea is first received until it is written up as an estimated issue and the requestor is notified exactly which aspects are scheduled for release. How intake works, and the estimation timeframe, vary per group, but every group has an estimation timeframe. -2. **Estimation:** The estimation process varies per-group. In the Interface group, it consists of drafting, API design, and either planning poker or a quick timebox decided by the group EM. When the Interface group relies on the Platform group for part of an issue, only the Interface group's work is estimated. It is up to the Interface PM to obtain estimated Platform issues for any needed work, and thus ensure it is scheduled in the appropriate release. It is up to the Platform PM to get those specced (in consultation with Engineering), then up to the Engineering to estimate and communicate promptly if issues arise. We avoid having more estimated issues than capacity in the next release. If the team is fully allocated, no more issues will be estimated, or the PM will decide whether to swap anything out. Once estimated, an issue is scheduled for release. +2. **Estimation:** The estimation process varies per group. In the Interface group, it consists of drafting, API design, and either planning poker or a quick timebox decided by the group EM. When the Interface group relies on the Platform group for part of an issue, only the Interface group's work is estimated. It is up to the Interface PM to obtain estimated Platform issues for any needed work and thus make sure it is scheduled in the appropriate release. It is up to the Platform PM to get those specced (in consultation with Engineering), then up to the Engineering to estimate and communicate promptly if issues arise. We avoid having more estimated issues than capacity in the next release. If the team is fully allocated, no more issues will be estimated, or the PM will decide whether to swap anything out. Once estimated, an issue is scheduled for release. 3. **Development:** Development starts on the first day of the new release. Only estimated issues are scheduled for release. -4. **Quality assurance (QA):** Everyone in each group is responsible for quality: engineers, PM, and the EM. The QA process varies per group, and is set by the group's PM. For example, in the Interface group, every issue is QA'd (i.e. a per-change basis), as well as a holistic "smoke test" during the last few days of each release. +4. **Quality assurance (QA):** Everyone in each group is responsible for quality: engineers, PM, and the EM. The QA process varies per group and is set by the group's PM. For example, in the Interface group, every issue is QA'd (i.e. a per-change basis), as well as a holistic "smoke test" during the last few days of each release. -5. **Release:** Release dates are time-based and happen even if all features are not complete (Β± a day or two sometimes, if there's an emergency. Either way, the next release cycle starts on time). If anything is not finished, or can only be finished with changes, the PM finds out immediately, and notifies the requestor right away. +5. **Release:** Release dates are time-based and happen even if all features are not complete (Β± a day or two sometimes, if there's an emergency. Either way, the next release cycle starts on time). If anything is not finished, or can only be finished with changes, the PM finds out immediately and notifies the requestor right away. ### Timeframes @@ -182,33 +182,33 @@ These are effectively internal SLAs. We moved away from the term "SLA" to avoid #### Prioritization -≀5 business days from when the initial request is weighed by PM, requestor has heard back from the group PM whether the request will be prioritized. +≀Five business days from when the initial request is weighed by PM, requestor has heard back from the group PM whether the request will be prioritized. #### Release -≀6 weeks from when initial request is weighed by PM, this is released into the hands of the Fleet community, generally available (no feature flags or limitations except as originally specced or as adjusted if necessary). +≀Six weeks from when the initial request is weighed by PM, this is released into the hands of the Fleet community, generally available (no feature flags or limitations except as originally specced or as adjusted if necessary). -Work that is prioritized by the group PM should be released in the 6 week timeframe (2 releases). Work that is too large for this timeframe should be split up. +Work that is prioritized by the group PM should be released in the six week timeframe (two releases). Work that is too large for this timeframe should be split up. #### Estimation -≀5 business days from initial request, an issue is created with a summary of the purpose, the goal, and the plan to achieve it. The level of detail in that plan is up to the PM of the product group. The issue also has an estimation, expressed in story points, which is either determined through planning poker or a "timebox". +≀Five business days from the initial request, an issue is created with a summary of the purpose, the goal, and the plan to achieve it. The level of detail in that plan is up to the PM of the product group. The issue also has an estimation, expressed in story points, which is either determined through planning poker or a "timebox." -For the Interface group "estimated" means UI wireframes and API design are completed and the work to implement them has been estimated. +For the Interface group, "estimated" means UI wireframes and API design are completed, and the work to implement them has been estimated. #### Adjustment -≀1 business day from discovering some blocker or change necessary to already prioritized and estimated work. The group PM decides how the usage/UI will be changed and notifies original requestor of changes to spec. +≀One business day from discovering some blocker or change necessary to already prioritized and estimated work. The group PM decides how the usage/UI will be changed and notifies the original requestor of changes to the spec. ## Product quality -Fleet uses a human-oriented quality assurance (QA) process to ensure the product meets the standards of users and organizations. +Fleet uses a human-oriented quality assurance (QA) process to make sure the product meets the standards of users and organizations. To try Fleet locally for QA purposes, run `fleetctl preview`, which defaults to running the latest stable release. To target a different version of Fleet, use the `--tag` flag to target any tag in [Docker Hub](https://hub.docker.com/r/fleetdm/fleet/tags?page=1&ordering=last_updated), including any git commit hash or branch name. For example, to QA the latest code on the `main` branch of fleetdm/fleet, you can run: `fleetctl preview --tag=main` -To start preview without starting the simulated hosts, use the `--no-hosts` flag (e.g. `fleetctl preview --no-hosts`). +To start preview without starting the simulated hosts, use the `--no-hosts` flag (e.g., `fleetctl preview --no-hosts`). ### Why human-oriented QA? @@ -232,21 +232,21 @@ The goal of quality assurance is to catch unexpected behavior before release: All QA steps should be possible using `fleetctl preview`. Please refer to [docs/Contributing/Testing.md](https://fleetdm.com/docs/contributing/testing) for flows that cannot be completed using `fleetctl preview`. -Please start the manual QA process by creating a blank GitHub issue. As you complete each of the -flows, record a list of the bugs you encounter in this new issue. Each item in this list should +Please start the manual QA process by creating a blank GitHub issue. As you complete each +flow, record a list of the bugs you encounter in this new issue. Each item in this list should contain one sentence describing the bug and a screenshot of the item if it is a frontend bug. ### Fleet UI -For all following flows, please refer to the [permissions documentation](https://fleetdm.com/docs/using-fleet/permissions) to ensure that actions are limited to the appropriate user type. Any users with access beyond what this document lists as available should be considered a bug and reported for either documentation updates or investigation. +For all following flows, please refer to the [permissions documentation](https://fleetdm.com/docs/using-fleet/permissions) to make sure that actions are limited to the appropriate user type. Any users with access beyond what this document lists as available should be considered a bug and reported for either documentation updates or investigation. #### Set up flow Successfully set up `fleetctl preview` using the preview steps outlined [here](https://fleetdm.com/get-started) -#### Login and logout flow +#### Log in and log out flow -Successfully logout and then login to your local Fleet. +Successfully log out and then log in to your local Fleet. #### Host details page @@ -298,11 +298,11 @@ Successfully set up Fleet by running the `fleetctl setup` command. You may have to wipe your local MySQL database in order to set up Fleet successfully. Check out the [Clear your local MySQL database](#clear-your-local-mysql-database) section of this document for instructions. -#### Login and logout flow +#### Log in and log out flow -Successfully login by running the `fleetctl login` command. +Successfully log in by running the `fleetctl login` command. -Successfully logout by running the `fleetctl logout` command. Then, log in again. +Successfully log out by running the `fleetctl logout` command. Then, log in again. #### Hosts @@ -352,7 +352,7 @@ Logout of your current user and log in with the newly created user. ## UI design ### Communicating design changes to the engineering team. -Something NEW that has been added to [Figma Fleet EE (current, dev-ready)](https://www.figma.com/file/qpdty1e2n22uZntKUZKEJl/?node-id=0%3A1): +NEW feature that have been added to [Figma Fleet EE (current, dev-ready)](https://www.figma.com/file/qpdty1e2n22uZntKUZKEJl/?node-id=0%3A1): 1. Create a new [GitHub issue](https://github.com/fleetdm/fleet/issues/new) 2. Detail the required changes (including page links to the relevant layouts), then assign the issue to the __"Initiatives"__ project. @@ -368,7 +368,7 @@ Something NEW that has been added to [Figma Fleet EE (current, dev-ready)](https ### Communicating unplanned design changes -For issues related to something that was ALREADY in Figma Fleet EE (current, dev-ready), but __implemented differently__, e.g. padding/spacing inconsistency, etc. Create a [bug issue](https://github.com/fleetdm/fleet/issues/new?assignees=&labels=bug%2C%3Areproduce&template=bug-report.md&title=) and detail the required changes. +For issues related to something that was ALREADY in Figma Fleet EE (current, dev-ready), but __implemented differently__, e.g., padding/spacing inconsistency, etc. Create a [bug issue](https://github.com/fleetdm/fleet/issues/new?assignees=&labels=bug%2C%3Areproduce&template=bug-report.md&title=) and detail the required changes. ### Design conventions @@ -384,7 +384,7 @@ Pressing the return or enter key with an open form will cause the form to be sub **External links** -For a link that navigates the user to an external site (ex. fleetdm.com/docs), use the `$core-blue` color and `xs-bold` styling for the link's text. Also, place the link-out icon to the right of the link's text. +For a link that navigates the user to an external site (e.g., fleetdm.com/docs), use the `$core-blue` color and `xs-bold` styling for the link's text. Also, place the link-out icon to the right of the link's text. ## Release @@ -393,7 +393,7 @@ and customer success team prior to a release of Fleet. ### Goal -Keep the business up to date with improvements and changes to the Fleet product so that all stakeholders are can communicate +Keep the business up to date with improvements and changes to the Fleet product so that all stakeholders can communicate with customers and users. ### Blog post @@ -446,7 +446,7 @@ The following highlights should be considered when deciding if we should leverag release. - The feature flag will not be advertised. For example, advertising in the documentation on fleetdm.com/docs, release notes, release blog posts, and Twitter. -Fleet's feature flag guidelines was borrowed from GitLab's ["When to use feature flags" section](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#when-to-use-feature-flags) of their handbook. Check out [GitLab's "Feature flags only when needed" video](https://www.youtube.com/watch?v=DQaGqyolOd8) for an explanation of the costs of introducing feature flags. +Fleet's feature flag guidelines is borrowed from GitLab's ["When to use feature flags" section](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#when-to-use-feature-flags) of their handbook. Check out [GitLab's "Feature flags only when needed" video](https://www.youtube.com/watch?v=DQaGqyolOd8) for an explanation of the costs of introducing feature flags. ## Competition @@ -458,7 +458,7 @@ Intake for new product ideas (requests) happens at the πŸ—£ Product office hours At the πŸ—£ Product office hours meeting, the product team weighs all requests. When the team weighs a request, it is prioritized or put to the side. -The team prioritizes a request when the business perceives it as an immediate priority. When this happens, the team sets the request to be estimated or deferred within 5 business days. +The team prioritizes a request when the business perceives it as an immediate priority. When this happens, the team sets the request to be estimated or deferred within five business days. The team puts a request to the side when the business perceives competing priorities as more pressing in the immediate moment. @@ -500,10 +500,10 @@ Directly Responsible Individuals (DRI) engage in the ritual(s) below at the freq | Ritual | Frequency | Description | DRI | |:-----------------------------|:-----------------------------|:----------------------------------------------------|-------------------| | πŸŽ™ Product huddle | Daily | We discuss "In progress" issues and place any issues that are "ready for review" on the list for the product design review call. On Mondays, issues are broken down into a week's work and added into "ready." We move issues out of "delivered" every Friday. | Noah Talerman | -| πŸ—£ Product office hours | Weekly (Tuesdays) | We make decision regarding which customer and community feature requests can be committed to in the next six weeks. We create issues for any requests that don't already have one. | Noah Talerman | -| 🎨 UI/UX huddle | Weekly (Wednesdays) | We discuss "In progress" issues and place any issues that are "ready for review" on the list for the product design review call. We hold separate time for πŸŽ™ Product huddle so Mike Thomas can make it. | Noah Talerman | +| πŸ—£ Product office hours | Weekly (Tuesdays) | We make a decision regarding which customer and community feature requests can be committed to in the next six weeks. We create issues for any requests that don't already have one. | Noah Talerman | +| 🎨 UI/UX huddle | Weekly (Wednesdays) | We discuss "In progress" issues and place any issues that are "ready for review" on the list for the product design review call. We hold separate times for πŸŽ™ Product huddle so Mike Thomas can make it. | Noah Talerman | | ✨ Product design review | Weekly (Thursdays) | The Product team discusses "ready for review" items and makes the decision on whether the UI changes are ready for engineering specification and later implementation. | Noah Talerman | -| πŸ‘€ Product review | Every three weeks | Fleeties present features and improvements in the upcoming release. A discussion is held about bugs, fixes and changes to be made prior to release. | Noah Talerman | +| πŸ‘€ Product review | Every three weeks | Fleeties present features and improvements in the upcoming release. A discussion is held about bugs, fixes, and changes to be made prior to release. | Noah Talerman | ## Slack channels