# Walkthrough (New 2023-12-12) :vhs: **Video walkthrough**: https://www.youtube.com/watch?v=SRM_EiW0YPM (19:06, but split into chapters for background, iteration plan, status categories, and initial design) # Background Status of individual items is a critical piece of information when reviewing<span dir=""> </span>and tracking work, providing insight into where something is in a workflow and potentially informing next steps. Today, Gitlab provides what we call (in code, not the UI) "state" - open/closed. Users then use labels to convey status, either as a set of scoped labels or discrete labels. Downsides to this approach include: * **Configuration:** Users have to configure status fields using labels, which requires mental mapping of "status" to "label" which is unfamiliar/unexpected for many users coming from other PM tools * **Identifying status:** Understanding status requires scanning all labels to find the status label on each item. * **Using status:** Like identifying status, users have to sort through all available labels to find the relevant status label. * **Reporting:** Any reporting using status requires mapping labels to a reportable status category, requiring users to do additional work to get insights. * **Requires labels to be priority:** Labels are displayed prominently in many places, in part because they capture this critical data that would otherwise be hidden. This was most recently elevated in the Plan UX Benchmark ([Actionable insight](https://gitlab.com/gitlab-org/ux-research/-/issues/2648 "2023 Benchmark Insight - Product Change: How do we enable users to use and see Status more effectively at a glance?")) More details in the [main epic](https://gitlab.com/groups/gitlab-org/-/epics/5099 "Configurable Work Item Statuses"). ## Users & JTBDs The primary users for configurable status will be **Parker** (Product Manager) and **Delaney** (Dev Team Lead). Parker and/or Delaney would typically be responsible for both defining team processes/statuses and setting them up in GitLab. They would also be the users utilizing status in downstream reporting to understand progress on initiatives and the performance of their team (e.g. in flow metrics), and in some organizations are responsible for updating status on individual items (such as in a standup). **Relevant jobs:** <table> <tr> <td>When evaluating and measuring previously delivered work, I want to surface and share any learnings identified while executing toward my strategy, so I can improve future plans based on these insights and articulate the rationale behind any changes.</td> </tr> </table> <table> <tr> <td>When reviewing a prior cycle, I can easily reflect on and improve my team's effectiveness.</td> </tr> </table> <table> <tr> <td>When monitoring progress, I want to ensure the current scope and status of work are thoroughly captured, so I can increase the accuracy of my reporting and maintain trust with stakeholder.</td> </tr> </table> \ Secondary users include **Sasha** (Developer) as a consumer of statuses, updating status on items they're working on and using status to find an item to work on next. Any user working on issues would have similar goals. **Relevant jobs:** <table> <tr> <td>When collaborating with a team or stakeholders, I want to radiate the current status of work continuously, so I can increase alignment on progress and any impediments that need to be addressed.</td> </tr> </table> ### Known needs Breaking down JTBDs and insight from research and customer requests: 1. Users need to track the status of planning objects to understand how they’re progressing. 2. Users today typically use labels, but would benefit from a status field which can stand apart and more easily be used in reporting/aggregation contexts. 3. As a replacement for status labels, any status field will need to be configurable (with defaults) since labels offer that ability to support each team’s workflow. 4. In many project management workflows statuses exist in a number of flow categories which are used in downstream reporting (e.g. active, unstarted). 5. Status configuration, as a replacement for labels, likely needs to follow similar group/path cascading behavior. ## Product considerations To understand how state/status is used today, I audited the current Plan experience including adjacent areas with potentially similar features. [**Full audit (Figma)**](https://www.figma.com/file/oRS2mDq5DnDEEUiiUW8TXg/Configurable-Status-(%265099)?type=design&node-id=1-2&mode=design) Summary of findings: * In all contexts we’ll need to define how we visually convey status. * In aggregation contexts, like list views, we’ll need a strategy for separating “Closed” state alongside ways to view by status * In any detail context, we’ll need to define if/how we convey state * We could: always show state, never show state, or only show closed * In any detail context, we’ll need to define if/how state controls interact with status. * We could: set status from state, exclude state controls (state only set via status) * In timebox contexts we’ll need to tie “in progress” classification to status to create a clear connection between the two. ## Competitive landscape To understand how state/status in the market, and what's familiar to many incoming GitLab users, I reviewed competing products focused on how they manage and apply status. Further analysis could be relevant around how status is used in reporting and other contexts. [**Summary (internal note)**](https://gitlab.com/groups/gitlab-org/-/epics/11975#note_1640166669 "[UX] Configurable status field design") | [**Competitive review details (Figma)**](https://www.figma.com/file/oRS2mDq5DnDEEUiiUW8TXg/Configurable-Status-(%265099)?type=design&node-id=0-1&mode=design) # Design plan To get to a complete design for incorporating status, we will need to complete the following: ### Background * [x] Evaluate existing use of state/status in the product, both related to planning items and other adjacent contexts, and identify both affected areas (where would we use "status") and potential areas of convergence/divergence (where is there an existing "status" concept we want to extend, or avoid overlapping) * [x] Evaluate use of state/status in competitor products to understand what's familiar and what configurations users may need to import when migrating to GitLab ## Iteration 1: Introduce Status _Outcome: Users can set a view and set status on Tasks from a predefined list of statuses, beyond open/closed._ _Start with Tasks: Issue workflows are deeply entrenched in user workflows and without a fully customizable solution, we won't be able to replace status labels resulting in an interim state where users could have to update both status and label status. While this can still be true of tasks, Tasks are in many cases used for smaller items of work that may require fewer discrete statuses — just knowing todo, doing, done will provide value in most cases and often may not require further status labeling. Tasks will allow us to build the component in the work item framework, without impacting issues or epics but with easy reuse in those items in later iterations._ **Breakdown** <table> <tr> <th>Description</th> <th>Design notes</th> <th>Status</th> <th> </th> </tr> <tr> <td> * [ ] **Users can view/change the status of a planning item** _(implemented on work items, enabled on Tasks)_ </td> <td> * What default statuses and if/how they're categorized (categories may not be user-visible in this iteration) * How status is shown on the detail view * How status is changed from the detail view * How users review status of a planning item in lists/boards, including in-detail lists (child items) * How status is used in timebox reports (iteration, milestone) - limited to tasks * _We may need to develop additional icons as part of completing this issue._ </td> <td> ~"workflow::ready for development" </td> <td> Design: https://gitlab.com/gitlab-org/gitlab/-/issues/383125+s </td> </tr> <tr> <td> * [ ] **Users can apply status using quick action on a planning item** </td> <td> </td> <td> ~"workflow::planning breakdown" </td> <td> https://gitlab.com/gitlab-org/gitlab/-/issues/431601+s </td> </tr> </table> ### **Validation needs** **Lightweight solution validation** to ensure users can find, understand, and update status. Risks here are low, this could be in the form of **internal testing and design reviews.** ## Iteration 2: Add configuration to Status _Outcome: Users can configure a custom set of statuses per group/project, which can be applied on all work items\*._ _`*` Status could be enabled for Issues and Epics in this iteration_ <table> <tr> <th>Description</th> <th>Design notes</th> <th>Status</th> <th> </th> </tr> <tr> <td> * [ ] **Users can configure status, including default statuses** </td> <td> * How users add/change a status * How statuses cascade from groups to projects * Who can manage statuses * How status is handled when moving items (if current status is not available in destination) * How status is used in timebox reports (iteration, milestone) – on all item types </td> <td> Management patterns have been validated. Group/project cascading remains\ ~"workflow::design" and relies on customization direction </td> <td> https://gitlab.com/gitlab-org/gitlab/-/issues/431600+s </td> </tr> <tr> <td> * [ ] **Users can easily migrate from label statuses to a status field** </td> <td> * Map labels to status, automatically update all planning items * Determine longevity/lifecycle of migration features </td> <td> ~"workflow::planning breakdown" </td> <td> https://gitlab.com/gitlab-org/gitlab/-/issues/463083 </td> </tr> <tr> <td> * [ ] **Users can edit issue status in bulk** </td> <td> </td> <td> ~"workflow::ready for design" </td> <td> https://gitlab.com/gitlab-org/gitlab/-/issues/431602+s </td> </tr> </table> ### **Validation needs** Full **solution validation** to ensure status categories align with user needs; users can easily configure statuses to match their organization; current users can easily transition from labels to statuses. * **Unmoderated usability tests** with broad profile of users to validate the overall experience of configuring statuses, one round or more if changes needed * **Targeted moderated usability tests** or feedback sessions with existing customers to validate complete support enabling those customers to migrate from labels to statuses. ### Iteration 3: Introduce per-type sets of statuses _Outcome: Users can configure statuses for each work item type, allowing them to get the right level of granularity for each type._ <table> <tr> <th>Description</th> <th>Design notes</th> <th>Status</th> <th> </th> </tr> <tr> <td> * [ ] **Users can apply different status options per planning item type** </td> <td> * Determine defaults _per type_ * Determine if users need to specify a flow of statuses and how that's used (e.g. knowing what the "next" status would be) * If Incidents use work items, determine relationship between paging status and workflow status; if same, use paging status as a workflow for Incidents. </td> <td> ~"workflow::start" </td> <td> </td> </tr> </table> ### **Validation needs** **Problem validation** focused on **scope** of "workflows" — understanding needs around visualizing workflows, rules or gates in workflows, and overall the types and characteristics of teams that need these workflows (as it won't apply universally). * Overall the need for workflow customization per type is reasonably well known based on existing customer behaviors. This is more about understanding those needs more deeply. * We could consider combining this with automated workflows to understand more completely the picture of user needs around managing workflows from setup to routine use. **Solution validation** focused on the usability of the experience for managing per-type workflows. * Determine methodology based on solution and findings from problem validation (do we have additional uncertainties, areas the solution may not fully address the insight, etc). _With this more advanced customization it's likely that roles and permissions will come into focus. This is much broader than status and too big to incorporate into this effort; aligning status permissions to labels will mean we can provide a better experience with at least the same limitations. A separate effort to understand needs around roles and permissions specific to Plan could include workflow configuration as a focus area — this effort would more holistically look at which users in a team should be able to manage Plan items and how that converges/diverges from managing other items, with a goal of understanding how we could better align Groups, Projects, roles, and permissions to Plan users._ ### Iteration 4: Utilize Status in reporting and analytics _Outcome: Determine how status can be incorporated into analytics to provide greater visibility into flow and bottlenecks._ * Users can utilize analyze performance using status — actual breakdown TBD ### **Validation needs** TBD based on the reporting focus; may overlap with other groups e.g. Optimize.