Help Center

Zenhub helps teams manage projects at scale, enabling multiple teams to collaborate and have ownership over the project planning process. Using GitHub issues and Zenhub Epics, you can track tasks, large-scale projects, and even small to-do lists.

• Checklists within Issues allow teams to understand how they're progressing on to-do's. 
• Issues track specifics the team is working on, keeping teams aligned on work in progress.
• Epics make it possible to organize information and keep track of how GitHub issues roll up into larger projects and initiatives.
• and Projects, as labelled through the use of Epics, help teams determine the scope and keep your roadmap on track.

Use Epics for themes of work, projects, and goals

It's important to first define whether a piece of work is small enough to be an Issue, or needs to scale into an Epic. First, consider the time it takes to complete a task and its complexity: Issues should be completed in the smallest amount of time possible, and be very specific. If an Issue will take weeks or months to finish, and has a lot of moving parts, it should probably be an Epic, with multiple Issues under it.

Likewise, if an Issue is too complicated (if multiple tasks are required to finish it), it's probably better as an Epic. Splitting tasks into easily completed pieces of work will help you ship valuable changes more often and reduce technical debt. It also helps you follow best practices for how to effectively plan and track Sprints.

Checklists VS. Issues VS. Epics

There are two ways in GitHub and Zenhub to create 'sub-tasks' or lists of work that need to be done. To help teams better scale projects and keep work organized, below are best practices for using checklists, Issues, and Epics.

Using markdown, you can create basic checklists:

And when you need to track the process of a bundle of work, for example, multiple GitHub issues and pull requests, you can roll these up to an Epic:

But when it comes to best practices for scaling projects, it's sometimes hard to understand how to best scale up and organize projects to manage work across the Board. We've shared a few tips below.

Questions to help determine when to use a checklist, Issue, or Epic:

• Checklists: Is this a to-do list, testing plan, or basic check before you consider something 'done'? If yes, use a checklist and keep things simple.
• Issues: Is what I am working on dependent on something else, or, have work that is dependent on this? If yes, use Issues to create the individual work items and be sure to use dependencies to indicate any blockers.
• Issues/Epics: Are the items I want to track going to be individually worked on, or picked up by multiple people? If yes, separate each piece of work into multiple Issues and bundle them together using Epics
• Issues/Epics: Is what I'm working on going to span multiple Sprints? If yes, create each individual piece of work as Issues and bundle them together using an Epic.
• Epics: Am I using an Issue with a checklist to track a long-term or large project? Use an Epic instead! Separate each checklist item into its own Issue, rolling all Issues into an Epic. This will help you clearly estimate work, have clear Issues, and help the team work in small chunks of work.

In addition to the questions above, here's an easy framework for defining whether something should be a checklist, Issue, or Epic:

• Use checklists when: you need to keep things simple and have a list of final to-do's and checks before moving something forward.

• Use Issueswhen: you want to track the piece of work across your Board (this piece of work will go through multiple phases, be accepted into the Sprint, and can be assigned to anyone).

• Use Epics when: you have large scopes of work, multiple moving parts, and need to see at a glance how complex something is.

A note on Issues, checklists, and Epics in Sprints

When you create an Epic, the Epic itself shouldn't be 'work' but rather, the container that keeps the project or bundle of similar Issues together. Each individual Issue should be what ends up in your Sprints, and shuffled on your Board. 

Only accept Issues and smaller pieces of work into the Sprint. Epics should not be estimated, but instead, help teams understand large-scope projects. When accepting work into the Sprint, be sure to break down Epics into smaller Issues that can be estimated and discussed. More on effective Sprint management here.