Planning objects IA and navigation concepts - feedback issue
This issue supports the OKR to Establish a consistent and comprehensive information architecture, data model and visual direction for the future of Work Items, specifically KR3 - https://gitlab.com/gitlab-com/gitlab-OKRs/-/work_items/1482+
Problems to solve
At a high level, introducing new objects that extend beyond epics and issues, such as tasks and potentially more in the future requires understanding where items will live and how users will navigate to them. Currently, epics are shown in epics lists (group), epic board (group), and roadmap (group); issues are shown in the issue list and issue board; tasks are shown in the issues list. The issues list also contains incidents and test cases, while boards contain incidents.
Defining a pattern that allows users to utilize these objects in an intuitive fashion, while also accommodating future growth, will ensure planning items in GitLab can be utilized to their fullest.
In addition to these general goals, specific user goals in the current product should be targeted, in particular:
Navigating across projects/groups, issues/epics, and lists/items is confusing
Users today struggle to understand projects and groups and where they are in relation to their planning items, including how to get to other items - for instance how to get to epics while in a project or how to get to a group from an issue.
Some of these are unlikely to be resolved exclusively though this IA exploration, but to the extent possible we should enable users to manage their plans with minimal navigation pain points.
Incomplete tools for representing organization’s work structure
Users whose project management processes rely on hierarchical structure of items are currently limited to epics (which can be nested), issues, and tasks. When using the Epics page today users can see Epics, but not the relationship of those epics to one another or to issues. These relationships are visible from within a single Epic, which is useful, but this still requires navigating across epics to see the hierarchy. Roadmaps provide a hierarchical view of all epics, but minus the corresponding issues or any epics without dates assigned, limiting a users ability to get a complete picture of a body of work at once.
Additionally, items work differently in at times unexpected ways. Beyond that finding these items requires different paths (noted above), Epics are lacking features both in their list/board views and in the Epics themselves, including different filters, and different attributes (Epics can't be assigned, or have designs, etc.). While some of these differences are purposeful, reflecting the expected usage of epics and issues, others are viewed as gaps which force users to use a different object than they otherwise would've.
Classifying items today often relies on labels, such as labeling issues as "Stories" or Epics as "Features" (in GitLab we do this as well, e.g. type::bug). By using labels, rather than a more structured approach, it becomes more challenging to capture the right data for each type and report on work by type. In each approach here, type becomes a first-class attribute which can be used to determine how an item is used.
Finally, the current project structure requires the organization of issues to mirror the organization of code, as each issue must belong to a project with a single repo. For users who take a more granular approach to repo management issues are less often 1:1 with a repo. Building this sort of structure requires workarounds to manage issues at a higher level such as creating a separate project just for issues, which both adds overhead to manage and means users have to navigate more often across projects/groups. This may not be fully resolved by this solution, but it should be considered as whether any solutions help address this issue.
Potential solutions
Direction A: Consolidated backlog (thread)
In this direction, everything defined as a planning item (Epics, Issues, Tasks) is mixed into a single list, which can be shown hierarchically or as a flat list. This would replace both the issue and epic list. In this model the focus is placed on the function of the view - the list optimized for browsing and searching and organizing by relationship, the board for reporting and organizing by attributes, and the roadmap for understanding timelines.
The consolidated backlog list would contain items that get planned and tracked together, including both the implementation-level items like Issues and higher level items like Epics. Users would have control over which items they see and how they would see them, including whether to view items hierarchically or just as a flat list. Combining this direction with "Saved views" can allow users to, by default, have views scoped to types e.g. an Issues-only list, an Epics-only list, and an "All" list, which can each be modified or removed.
As new objects are added to GitLab, only items that get used in similar ways to backlog items would appear in this list. Items that are used in different ways, which don't fit the "Backlog" model, would exist in their own list.
Navigation summary
| Before | After |
|---|---|
|
Issues |
"Work items" (name TBD)
|
| Cons | |
|---|---|
|
|
Direction B: Implementation levels (thread)
In this approach, separate navigation is provided for issue-level items, which are implementation oriented, and epic-level items, which are more organizational. The overall structure of the Issues list and board remain as-is from the current state, but additional tools are added to bridge the issue/epic gap such as grouping by epic, showing parent items in the list, and bringing a list of epics in alongside the issue list/board. The epic list is changed to a hierarchical "portfolio" view, similar to the current epic tree but spanning all epics in the group. This gives PM users a top-down view of all their planned and in progress work for both tracking and prioritizing at different levels.
Navigation summary
| Before | After |
|---|---|
| Issues Issue board Epics Epic board Roadmap |
Issues Issue board Portfolio Epic board |
| Pros | Cons |
|---|---|
|
|
Direction C: Abstract collection (thread)
While direction A and B are direct alternatives, the Abstraction approach can be used in conjunction with either. In this approach, an entirely new area is created that allows users to create "plans" (actual name TBD) and manually define what items live in those plans. This could include all items from a group or project, or just some items, or items from entirely different groups/projects outside of where the plan lives. As in other approaches, Plans can be viewed hierarchically or flat, and the list of data shown could reflect the union of data across types on the plan (i.e. both fields on epics and fields on issues).
Plans could exist in any namespace including personal namespaces. While not required for this approach to work, new items could be created directly from the Plan, which could allow users to create items outside of their normal organizational placement (e.g. an issue in a group-level Plan).
Data and attribute ownership
We explored two potentials for how data would be managed. In one model, all data is owned by the work item. This means that the data for the same item is the same across any collection the item belongs to. This means that data in the collection is not standardized, and items from different groups/projects in the same collection will utilize different milestones, different labels, different statuses, etc. This is most similar to the current group-project model. One downside of this model is that if for instance you create a collection pulling in items from many places each using different attributes there will be no way to standardize the information into a board; this is not dissimilar from existing limits in groups and teams using a standard set of attributes created in a top-level group should see minimal impact. Allowing users to create arbitrary groupings within a collection, not tied to attributes, could be one approach to allow common grouping where the attributes remain distinct (example: I create a "now" list in my personal collection board, and add 2 items that would otherwise be "in progress" and "in development").In the other model, we would allow items in the collection to utilize a common set of attributes, either owned by the collection itself or by the namespace in which the collection lives. In this model a single work item would have multiple values for some attributes, first for the "home" and then for any collections it belongs to, for instance if we added a status field as shown this could mean that issue orange#12 has a status of "In development" in the project orange and "In progress" in collection group/mobile app. When viewing the item you'd see any collection values you have access to. This model adds significant complexity given existing group/project ownership of these attributes, and the potential for confusion with conflicting values.
We've prioritized the first model, where all data is owned by the work item and can only have a single value corresponding to the values available in the work item's "home" location as this is more simple to understand and manage, and aligned to existing patterns.
Navigation summary
* As the collection concept could contain both boards and roadmaps it could replace those pages. The main difference would be that where e.g. Group > Issue board contains all issues from within that group, Collection > Board may not, though we could create a system-built collection providing these same items (e.g. treat "Issues" as a pre-defined collection of all the issue-level items in the namespace)
| Before | After | Future consideration* |
|---|---|---|
| Issues Issue board Epics Epic board Roadmap |
Issues Issue board Epics Epic board Roadmap Collections |
Issues Epics Collections |
| Pros | Cons |
|---|---|
|
|
Alternative approach: Cross-location Sharing
Read more
One of the key factors of the Collection approach is the ability for content to appear in a group it wouldn't normally appear in, such as content from a parallel or higher-up group appearing in a collection in a lower-level group. Allowing content to be shared to other groups could additionally provide this functionality - I could share this issue in `gitlab-org/gitlab` to `gitlab-org/plan-stage`, where `gitlab` remains the owner but it now appears in `plan-stage` lists and boards. Combined with the Consolidated approach, and Project/Group filters, this could provide generally similar outcomes to Collections.The main disadvantages to this approach, when compared to Collections, is that it may be more difficult to understand the different expectations for shared items, which will appear alongside items owned by the group. In one list, you'll have 2 classes of items that may work differently. In a Collection all items are equally "unowned" by the collection, and the expectations for Collection items can be true for all items in the Collection. Collections additionally provide navigational tools that sharing alone would not, such as the ability to link an item to a collection - you cold link an item to its shared group(s), but not a specific board or view in that group.
Sharing is not mutually exclusive with Collections, however to solve the primary needs for work structure and navigation we are primarily considering the discrete "Collection" approach.
💬 Feedback requested
In each concept, the design is not high fidelity or intended to convey any ready-to-build UI. Realistic(ish) data is shown to help visualize how different data types would appear, but we are most interested in feedback on how content is organized and how users would navigate to build, prioritize, and track work for themselves or their team.
- For any concept, what pros/cons stand out? Are there ones we've missed, or which feel particularly significant?
- What other ideas should we consider within each concept?
- Are there concepts we should consider that aren't shown here?
How to leave feedback
Figma: Each concept has a link to the screens in Figma, comments here are a great way to tag items in context.
Threads: Each concept has a corresponding thread which can be used for any feedback.
-
👍 and👎 can be used on each direction thread to indicate directions you find more or less successful at solving the problems we hope to address.
Sync sessions: Grab time on my calendar (nleonard@gitlab.com), or indicate your interest in this here and I can reach out and/or invite you to any upcoming discussions.
Wireframe notes
- As previously noted this is meant to show readable data, but is not high fidelity or ready to build. Any changes to board/list presentation are for demo purposes only.
- In general existing Issue, Epic, and Task attributes (e.g. labels, iterations) won't change as a result of any direction.
- We are showing "Status" as a field as that is expected to be added, and is an area where we will need to consider how status is the same or different across groups/projects or even across types. While not deeply explored here, including this may help further those discussions once relevant. In particular this was initially part of exploration for the Abstraction concept, and whether "Status" was owned by the work item itself (one status per item) or by the collection (one status per item per collection, so an item could be 'in progress' in one and 'in development' in another).