Skip to content

Small team uses issue board

Problem

We currently have the basic framework for an issue board. It is a very versatile framework that can be applied to many scenarios, including:

  1. High-level progress health status and high-level planning of many issues rolled up into epics, groups of issues, etc.
  2. A tool for small teams in organizations (from small startups to big companies) to manage their day-to-day work, using agile, scrum, kanban, etc. style methodologies.

The current product strategy is to focus on delivering features for the latter scenario.

Deliverables

  • Define and design some high-level paradigms for issue boards to pursue in 2017Q1.
  • Produce some high-level design artifacts that would guide and unify the team as we proceed. Maybe rough wireframes, personas, user story maps, journey maps, etc.

Out of scope

  • The output of this exercise is not a list of features. It is instead some artifacts that we will distribute and share publicly about our issue boards direction. Design and Product should re-group after this exercise to quickly set a direction and create the list of features to pursue.
  • Team execution metrics are out of the scope for this high-level planning issue. This is a key tool in retro and planning. But it is being tackled within the context of cycle analytics.

User mapping

Our designs should tell these stories. A typical small team consists of:

  • 1 product manager (PM) or business analyst (BA) who interfaces with business stakeholders. The granularity of the board (in this issue scope) is too detailed for business stakeholders and not useful for them. The PM/BA lives in the board day to day, managing issues to ensure the team is building the right product and delivering iterative business value. The PM/BA is heavily involved with prioritization, order of delivery, and timelines. The board helps with these project management needs.
  • 1 interaction designer (ID) and/or 1 visual (VD) designer who takes the product concept and creates a coherent user experience. The designer(s) creates wireframes and/or compositions and works with the PM/BA and EM (below) to create a backlog of issues that progressively realize the design vision in an experimental and iterative manner. Each issue should stand on its own but be easily relatable to other issues when viewed on the board.
  • A small group of engineers (less than 5) who create the software, including frontend/backend/database/full stack engineers and test engineers. Engineers collaborate closely with the designers and the PM/BA throughout the lifecycle of a single issue: i.e. scoping/requirements, construction, testing, shipping, and production validation/support. That single issue should easily flow between all those stages and be reflected in the board for all to see.
  • 1 engineering manager (EM) or engineering lead (EL) or scrum master who leads a small group of engineers. The EM/EL manages work and technical dependencies for the engineers, helping to ship features on time. The EM/EL works with the PM/BA to lead ceremonies (standups, planning meetings, retros, etc.) with the board being a crucial tool in those ceremonies. The EM/EL is responsible for the high-level technical execution so that the engineers can focus on single issues at a time. The board should be a key tool for this, including effort estimation and project management in general.
  • The small team size and focus on iterative delivery implies high-collaboration and that only a small amount of work is ongoing in the pipeline at a given time. So the design should reflect this scenario where the initial non-started list of ideas is large, the number of ongoing issues is small in the intermediary steps, and the final placeholder of completed issues gets big over time. The focus of issue boards (for this high-level design) should be in the middle steps, and not on the two ends.

Small team process

We should design issue boards to solve the problems in a typical agile/scrum process. Kanban is an extreme and should use a subset of the features. Many of the ideas are summarized here: https://www.atlassian.com/agile

| What to build and prioritization | Sprint/iteration/milestone planning | Technical collaboration | Daily standup | Demo / UAT | Iteration review + retro | Customer feedback | | --- | --- | --- | --- | --- | --- | --- | --- | | The PM works with business stakeholders to determine what to build, and prioritizes features based on business strategy. They regularly sync up and re-prioritize, planning and reacting according to timelines appropriate for their company and industry. The PM maintains a prioritized backlog of features, typically using an issue tracker. The PM also maintains a product roadmap to help business teams plan for upcoming features. | At the start of a sprint, the PM works with the engineering and design team to schedule a number of features to build. Based on business priority and technical feasibility, these features are committed to be completed during that sprint. These features are typically moved from the backlog into the current sprint's "Ready for dev" list. No new features should be added to the sprint after it has started. | Engineers and designers work on the features, moving each one across stages such as "Ready for dev", "In code review", "In QA", etc. Typically, each stage is represented by a list, with features/issues moving across the lists. The EM uses the tool to ensure resources are working on the right issue. For example, because of technical dependency reasons, a QA resource should test one issue before another. The EM can then prioritize the issues in the "In QA" list accordingly. With a quick glance of the tool, any resource should know right away what they should be working on, and have a view of how the team is doing overall. | Every day, the engineering+design team has a quick sync up to know what each person is working on. Typically, they refer to the tool to see which issues are in which stage holistically, in order to make any quick adjustments to the plan within that sprint. For example if the sprint is almost about to end, and many features are still in flight, the EM+PM may make a decision to focus on a smaller number of issues to ship, and cut out scope from the sprint. | Typically toward the end of the sprint, the engineering team demos working software to the PM and other business stakeholders before features are shipped. This allows for final tweaks before shipping the features. | After the features are shipped, the engineering team and business stakeholders look at what was accomplished and reviews business goals. The engineering team has a separate meeting to see where they can improve in their process. The tool should help with these use cases. | Once the features are shipped into production, customer feedback (qualitative and quantitative) is captured. This should be recorded and linked back to the issues for future analysis and business strategy. |

Existing problems with current issue boards implementation

Some things that @victorwu thinks are problems. Pending further discussion with team.

  • https://gitlab.com/gitlab-org/gitlab-ce/issues/24685
  • We are already using labels for 2 functions. "Labeling" an issue to reflect it's content. Using priority labels to assign priority to an issue. And now with issue boards, we are adding a third concept, i.e. creating a "stage" in the issue board. We are overloading 3 functions for one UI element. That's a lot to expect the user to remember and be aware of. Since likely we will not change this design for issue boards, we have to be very careful in supporting this third use case, and help users not to do unexpected things. For example: A user might innocently see a label called "ready for code review", and apply it to an issue, outside of the context of a board. As a result, that issue which was not intended to be shown on the board, now suddenly appears there, incorrectly.
  • Labels themselves are worrisome to apply to stages. What if an issue contains labels from multiple lists? Is that the intended use case? How do we make it clear to the user what is the intended use case?
  • In addition to labels representing stages, we also have to stages called "Backlog" and "Done". This introduces an additional complexity because whether an issue belongs to a list or not depends on both it's labels, and it's open/closed status. To alleviate some of the pain, maybe we should use words that borrow from the status, like closed for the final column. This likely needs some customization. But it may be difficult to create something that is intuitive and not overly complex.
  • When dragging an issue between lists, is it clear we are removing and adding labels on the fly? What is the mental model? This is related to the greater discussion above of the concept of using labels to represent lists, as above.
  • Concept of filters seems to imply individual personalization, when the board should be for a common view across teams. The underlying tech will probably be the same (i.e. filtering on milestones and labels and saving it), but the UI should present it not as individual personalization, but a team-wide setting that may auto-update. For example, advance to the next milestone when/if appropriate.
  • What is the purpose of upcoming in the milestones dropdown.
  • Create list button is prominent. Does this imply / optimized for frequent use? Once a board is set up, it shouldn't need to change much.
  • When we create a new board, we suggest some default lists, i.e. "to do, "doing", etc. These are good, since they imply stages, which is exactly the whole point of issue boards (at least that should be are target use cases). But we also allow users to easily create a list that is labeled for example, "direction", which has nothing to do with stages. With this much freedom, are we empowering the user, or are we actually confusing them. Our product should be focused and guide the user to use it as designed.
  • There is UI to delete a list. Is it clear that this is just deleting the list from the board? Does it delete the issues? Does it delete the label? Why is it so easy to delete a list from the UI? (Similar to adding a list in the UI.)
  • Why is it so easy to navigate between boards? The system should send me to the right board easily, and I shouldn't see prominent navigation to go somewhere else, because most users are not surfing between boards. Probably a low-priority problem to solve, if at all, since users can easily bookmark a URL, as long as our implementation implicitly allows that.
  • About 1/3 of the vertical space is for settings / navigation. Any way to help with that? May not be a high priority. Nobody has complained about it afaik and people have large (tall) screens.

New problems to solve with issue boards

  • https://gitlab.com/gitlab-org/gitlab-ce/issues/21264 asks to solve the simple problem of reordering within a single list, and that is the scope of it. But longer term, how do we harmonize re-ordering / ordering in general? When an issue moves between lists, does the relative order with respect to other issues remain? How do we determine initial ordering in a list? How do we harmonize with priority labels? There's likely a lot of technical implications with this. We can likely get away with just solving the smallest scope, least restrictive version documented in the issue first, and delay anything after. (For example, if a user has to re-position / re-order an issue after dragging it to another list, that's okay.)
  • How do we add issues to a board? Currently the system assumes the user has labeled all issues carefully and correctly, and followed a strict process to do so. More likely, people apply labels haphazardly (which should be okay, but that's another discussion for labels in a different context). And if we ever lower the friction of creating labels, people will just keep creating labels on the fly for new issues. So if that is the case, we should not assume a label-first workflow. The issue board should allow people to easily "add" issues to an issue board, whatever that means. There's an issue board created for my team. I want to add some issues to my board for the current sprint / milestone / iteration. Where's a pool of issues that I care about, and can easily pick and place into my board?
  • As a team, I work in single sprints / iterations. At the beginning of each iteration, I choose a bunch of issues I care about into my board, and then I focus on them. I care less about the other issues outside this sprint. At the end of the iteration, I ship the issues that I can, and for the issues that I didn't finish, I might want to move them back to that master list of unpicked issues, or maybe move them to the next iteration. How do we solve these scenarios?
  • How is it clear that every time I load the board, I'm viewing the current issues I care about, namely the ones in the current iteration? I shouldn't need to hunt around to go to the specific iteration version of my board.
  • Kanban doesn't have concept of iterations. A kanban team could probably tweak our tool to make it work. So we don't have to design specifically for kanban. But we should make sure our designs are not so restrictive it makes it impossible for them.
  • Non-problem: We shouldn't need to overly worry about long lists and paginating through them. In our initial use cases, each list should be short enough to fit on a screen. Our scenarios are short lists in which users can quickly re-order to represent priority. Long lists imply different use cases we should not be focused on right now.
  • Iteration planning information like total estimated points included (sum of issue weights), team capacity, burndown information, retro views of an iteration, etc. are much further down in priority. We can solve these problems later, and they may or may not deeply be integrated into issue boards initially. Something to think about in our design of issue boards as a tool for team collaboration, but not of high priority and prominence now.
Edited by 🤖 GitLab Bot 🤖