Setting up your first ZenHub Board

About ZenHub Boards

ZenHub adds advanced multi-repository boards into GitHub. Inspired by kanban boards – a flow-oriented approach to development – ZenHub's boards present a simple yet incredibly robust picture of your software projects.

Think of task boards as rich information broadcasters about your entire software organization. They allow you to track GitHub Issues and Pull Requests end-to-end through the release cycle.

Instead of tickets or sticky notes, ZenHub's Boards are made up of your existing GitHub data: Issues and Pull Requests. Let's look at the anatomy of a ZenHub Board:zenhub-board-highlight

Why we visualize our workflows

The ZenHub Board can be described as an ‘information radiator’, but more than that, it provides a compelling point of focus for teams to answer important questions: “What are our current priorities?”, “What are our highest priority Issues?”, “Do we have any blockers? Are we on target?”

A great task board provides immediate visual cues and feedback to these questions. By keeping all priorities organized with GitHub Issues and the ZenHub Board, teams get an immediate visual representation of every project’s status.

When you create a ZenHub board, each “card” on the Board represents a GitHub Issue. Each card sits within a column, or Board pipeline. Issues can be dragged-and-dropped between pipelines as they get worked on. This movement represents how tasks and stories get completed within your workflow.

ZenHub makes it very easy to change the layout so as Issues move throughout your workflow, where they sit within your workflow can also be visualized on the Board.

Pipeline defaults on the Board

ZenHub Boards come with six default pipelines to start with: New Issues, Backlog, To-Do, In Progress, Done, and Closed. It's a standard kanban-like setup that suits most projects, but can also be customized to suit more unique workflows.

Regardless of how you customize a board, GitHub Issues and Pull Requests should move left to right as they get closer to completion. But it's not only the job of a project manager: in a high-functioning team, everybody participates by dragging Issues as they progress through the development cycle. The key to making it possible is a well-organized board.

Here's a quick overview of what each default pipeline means.

  • New Issues: New Issues land here automatically. You should drag (triage) them out of here as soon as possible.
  • Icebox: The Icebox represents items that are a low priority in the product backlog. Leaving Issues in the icebox over deleteing them helps avoid a cycle of raising duplicate Issues. Icebox Issues should not take up a team member's time or mental bandwidth; putting ideas into the Icebox Pipeline gets them out of the way and helps teams focus on immediate priorities.
  • Backlog: Backlog Issues are not a current focus, but you will act on them at some point. If they don't have a GitHub Milestone, you can consider them part of your “product backlog”. Once you add a Milestone, they become part of your “sprint backlog” (that is, the tasks that you'll complete in an upcoming sprint.) The process of keeping this pipeline organized is known as “backlog refinement”.
  • In progress: Issues here should have a good amount of detail, like estimates and requirements, since they're your team's current focus. This is the answer to, “What are you doing now?” Ideally, each team member should be working on just one thing at a time. Tasks here should be ordered by priority with Assignees added.
  • Review/QA: Use the Review/QA column for Issues that are open to the team for review and testing. Usually this means the code is ready to be deployed, or already is in a Staging environment.
  • Done: If you ask three people what “Done” means, you might get three different answers. That's why it's so important to have a discussion as a team about your “Definition of Done”!

Match pipelines to your workflow

A well-organized task board can help you uncover bottlenecks faster and provide more information for other stakeholders on the team. While the default board structure is a great starting point for any project, you should consider customizing it to suit your workflow.zenhub-board-edit-name

When thinking about how to customize your task boards, take an audit of your team's workflow. Look at your boards and ask yourself these questions.

  • Does this structure contain only what we need, and nothing more? Could my boss look at this and understand everything she needs to about the project?
  • Is every important stakeholder represented? Can someone in design, marketing, or QA look at this board and know exactly where his or her help is needed?
  • Are we missing any repeating stages? Think about how your team builds products. It's all about keeping issues flowing across the board. If you have a QA department, for example, you might need a “Ready for QA” pipeline.
  • Is “Done” really done? And does my team know and understand our definition of Done? This often-missed step is a crucial part of any agile project.

Organize your Board using multi-action

Multi-Action eliminates the onerous process of performing certain actions over and over again. Selecting multiple Issues on the Board will trigger the Multi-Action action bar allowing you to get to a functional Board quicker.etting-started-with-multi-action

You can select multiple Issues in two ways. First, you can simply click a profile picture to select the first Issue:zenhub-board-multi-action-select

Once your first Issue is selected, you can continue highlighting additional Issues by clicking on them. Once you've selected all relevant Issues, find the bulk action you want to perform at the top of your task board:zenhub-board-multi-action-bar

You'll notice that the Issues remain selected so that you can make additional updates if needed. Click either “Done”, “clear all” at the top-left corner of your board, or unselect all of the Issues by clicking on them again to exit selection mode completely.

This is also a handy way to start organizing your work and standardizing your workflow. You can update labels, assignees, Milestones, Epics, and make movements between pipelines to Issues and Pull Requests at once.

Bonus tip! If you're viewing a board that contains multiple repos and you apply labels or Milestones to a group of Issues, ZenHub will attempt to create those labels or Milestones in repos where they didn't previously exist.

The importance of a product backlog

If you're seeking a GitHub Issue tracker, Boards can be one of your most powerful tools – but they're only as useful as you make them.

A product backlog represents feedback from multiple sources, like other developers, sales, business development, but most importantly, your users. It's your job to take in that feedback, prioritize it, manage it, and work it into the future of your product.

Without a process, your Boards can become clogged with inactionable feedback and a lack of focus. In contrast, a well-managed backlog leads to a more efficient and focused team. The result is a better product, and one that your customers actually want to buy.

Here's our recommended sprint-based workflow that can help bring clarity to your product.zenhub-board-workflow

  1. New feedback and ideas automatically land in the New Issues pipeline.
  2. The product owner reviews each Issue and figures out if it's actionable.
  3. Note: “Product owner” refers to whoever makes the ultimate call as to what is built and when. Typically, it's a project or product manager.

  4. If you intend to complete an Issue but it's not ready for development (ie it needs more detail or the team has no capacity for extra work), the Issue is dragged the Backlog. Issues here don't yet have a Milestone. You'll add one at the beginning of a sprint.
  5. If it's a valuable Issue but you have no plans to tackle it in upcoming sprints, “freeze” it in the Icebox pipeline.
  6. If the issue isn't going to get done, just close it. If it's really that important, you can always re-open it later!
  7. Is an Issue ready for action? At this point, your team should have added details, like acceptance requirements, and a user story (a short feature description as told from the perspective of user benefit.) Your engineers should have added an estimate. Once an estimate and a Milestone have been attached to an Issue, it's formally part of your “Sprint Backlog” (the stuff you'll tackle in the next sprint.)
  8. When the sprint begins, simply filter the Board by Milestone to see what needs to be done. Team members can drag tasks off the top of the backlog to indicate they're being worked on. Simple!