Just like a regular ticket, an epic has both an assignee (which we refer to as the epic owner) and a reviewer (which we refer to as the epic reviewer).
Concrete expectations that we have for epic owners are laid out in the epic owner role of this handbook. To get a refresher on these expectations, go ahead and have another look at that section now.
The main role of the epic reviewer is to take over the responsibilities of the epic owner while they are away, as well as any additional tasks and responsibilities that are specific to a given epic. It is the responsibility of the epic owner to coordinate their time off with their epic reviewer.
Also keep in mind that if you do the discovery for a future epic, you will be expected to take on the epic owner role for that epic later on (if/when the client gives us the go-ahead for starting the work).
Project management for non-project managers¶
A lot of the work involved in epic ownership falls under the category of project management. We strongly recommend every epic owner read through Atlassian's excellent guide "Project management for non-project managers: The steps, skills, and troubleshooting techniques you'll need to deliver the goods without losing your mind".
As described in that guide, there are some things that every epic should have in place. We've summarized them in the checklist in the epic description template below.
If your project is a large one (>1000 hours), you should also read Estimating Large Projects. If your project has grown large over time, it's a good idea to schedule a discovery task to determine if some changes to communication, approach, or scope can help keep the project manageable.
Tips and tricks¶
Here are some tips/tricks/strategies concerning different aspects of epic ownership that should be helpful to you going forward.
Be mindful about the number of epics you take on as an epic owner. If you're new to epic ownership, it's best to focus on a single epic; and even if you have some experience managing epics, it's better to keep the total number of epics that you own fairly small. Otherwise you'll need to do a lot of context-switching during the day/week/sprint, which tends to affect productivity and can even become frustrating at times. Also, if you own too many epics it can be hard to devote enough time to managing each one and being proactive where you should be. As a rule of thumb, aim to own one or two epics at most.
Keep your epic to a manageable size. If necessary, break a big client project up into smaller phases and pieces, with each phase/piece becoming a separate epic. See Estimating Large Projects: Create manageable deliverables for more details.
When estimating for an epic, add estimates to onboard developers into the project, and after kicking off the epic, take some time to write what’s needed to get set up and working. Also consider the technologies you’re dealing with (React, Terraform, etc), and add some more onboarding time to cover that too. See Estimating Large Projects: Consider your team for more details.
If the discovery just provided ballpark estimates, take a good chunk of time when the epic is kicking off to sort things out. If estimating in ballpark estimates, go for overestimation, and consider that the work in the epic will have to cover a full estimation of every requirement. See capturing the technical requirements for more details.
Prepare to delegate work: before delegating work to others, make sure the tickets in your epics have proper setup instructions and that the requirements are crystal clear, so that team members and newcomers can take on tasks. Otherwise you risk running into spillovers and going over budget, which can impact the original epic plan.
Plan to get newcomers involved after some core team members are onboarded, so that they can help the newcomers get up to speed quicker and use their time more efficiently. Also, if newcomers end up with stuck tickets, then core team members are better equipped to recognize the issue and step in to help.
Don’t assume client expectations, set them clear early on: make sure the client knows exactly what they're getting, and if possible, make a clear section explaining what's not included in the work. Sometimes clients come from past assumptions that might lead to disappointment (e.g. some providers include ecommerce features in the "default" package, while we don't). See Estimating large projects: Developing a shared understanding of requirements for strategies.
If you don't have time to manage the project while doing dev/ops for it, stay involved in the day-to-day work by taking on task reviews, and at least some small tasks. If the project is large, split the operations and development work into separate epics, with one person owning the ops and reviewing the dev epic, and the other owning the dev and reviewing the ops epic. That way, you can stay informed about the whole project.
Choose a communication channel to communicate overall project strategy, process, or scope changes to the rest of the development team. For example, starting a forum thread for the project is a good way to do this, and also allows the team to communicate development or deployment process changes to each other.
Epic Description Template¶
When creating an epic on Jira, here is a template you should use, in the same way as we have the task description standard for regular tasks.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
Below is a list of points to be aware of when performing a discovery for a new project/client.
- Before writing the discovery, get clarity on the level of detail that is required. If the ticket description doesn't say, ask the person that created the ticket whether you should do a high-level discovery with ballpark estimates, or a more detailed discovery with stories and detailed estimates. Make sure to read the entire documentation on how to do estimates at least once, and reference relevant parts of it while doing the discovery.
- Most discoveries are timeboxed, so plan your time carefully against the requirements of the discovery. If you don't have enough time to go into detail on a particular part of the estimation, either designate it as something that will require further investigation, or give a quick ballpark estimation range.
- Think about whether or not it would make sense to set up a weekly stand-up meeting with the client for the duration of the project. This is especially important if multiple teams are involved in the project.
- The purpose of that meeting would be to provide status updates to the client, get status updates from other teams that are involved in the project, address any open questions, and make sure all parties are unblocked and clear on the next steps.
- It should be enough to allocate 30-45m per meeting.
- It's important to determine whether this is something that the client would want prior to the implementation phase because we will need to account for it in the discovery document and quote that we send to the client. A budget of 1-2h per week for meetings should work well in most cases. (Note that it can't just be 30m because you'll also need a little bit of time to prepare for/follow up on each meeting.)
- Don't schedule the weekly meeting (or any other meeting that you might need to set up over the course of the project) for right before your EOD. To make sure you'll have time to list out (or directly follow-up on) any action items and add your notes from the meeting to existing tickets as necessary, the meeting should end no later than 30m to 1h before the time you normally stop working.
- Discuss the hours requirement for the project with the cell's epic planning manager and Braden and/or Xavier, so they can determine whether we have capacity within the team for the project, or need to hire to accommodate.
- Note that the number of hours that OpenCraft can allocate to the project per month might differ month-to-month. If that's the case you'll need to keep it in mind when planning out different phases of the project, and when scheduling stories for specific sprints.
- If the project has a deadline built-in (such as the start of a course that is supposed to be using a set of features to develop as part of the project), the number of hours that OpenCraft can allocate to the project will affect the scope of the project. (More specifically, it will be an upper bound for the amount of work that we can schedule and complete prior to the deadline.)
- If the project does not have a deadline built-in, the number of hours that OpenCraft can allocate to the project will affect the duration of the project.
- Leave time for a QA phase after delivering the features laid out in the discovery document. This is especially important for projects that are about developing features that a client wants to use in an upcoming course. Ideally, you should allow 2-3 sprints for QA for projects with specific deadlines, but 1 sprint is the absolute minimum. If you only have 1 sprint for QA, make sure that the client delivers their feedback within the first half of the first week of that sprint. Otherwise it will be very tricky to address their feedback, deploy changes, and give the client enough time for another round of testing before the final deadline (which might coincide with the start of a course that depends on the features developed over the course of the project).
- If your epic has any dependencies on edX (product approval of the plan, PR reviews, etc.) then leave lots of time for those to happen and have a contingency plan for what to do if edX delays things too long. Also, try to get specific people from edX to be aware of the project and its timeline, and to commit to being available for product and technical reviews.
- Keep in mind that OpenCraft has a policy to upstream as much work as possible. That aspect can have a major impact on the budget and timeline of a project and should therefore be taken into account right from the start. In some cases it might be necessary to reduce the scope of the changes to include in an epic, to make sure that the client's budget will also cover the costs for upstreaming those changes.
Capturing the technical requirements¶
When capturing techinical requirements we want to establish a shared understanding between the client and the development team. There must be written acceptance criteria, and the client's primary contact / product owner should review them before work begins on the feature, either on the discovery document or on the task description itself.
To achieve a shared understanding between parties we follow the Behavior-driven development principles. Behavioral specifications describe the various actions users can perform in the software and the expected response of the software. Relying solely on UX designs alone is not sufficient as specifications - because too often these do not capture the error paths, or can hide an assumed complexity of features.
When writing these specs out they should be expected to be used for 3 purposes:
- Help dev and product agree on how the system should behave from the point of view of the user.
- The end to end tests should map directly to these specs. They don’t need to cover all the possible situations but should cover the common ones.
- The specs should also be used during manual testing and verification by code reviewers and QA.
What should they include?
- Each spec should be written in the form: "When the user \<action>, \<response>”
- The specs should include the common happy paths.
- They should also include paths which result in errors.
Examples of behavioral specs¶
LX-1764 UI update: show only those tabs on the content picker modal that contain content visible to the user
When a user views the content picker:
- editing a pathway or composite asset
- adding assets to a classroom
- assigning assets to a mentee
- if the user
- is an org member, the "Org. library" tab is visible.
- is not an org member, the "Org. library" tab is not visible.
- has marked assets as favorites, the "Favorites" tab is visible.
- has not marked assets as favorites, the "Favorites" tab is not visible.
- has created assets, the "My content" tab is visible.
- has not created assets, the "My content" tab is not visible.
LX-1176 VideoJS: Add Vimeo support
When a user wants to add a Vimeo video as an asset:
- they click "Add new content" on the dashboard and then select Video a modal shows up.
- the modal has the Youtube logo, "To add a YouTube video.." text, the url field and "Import Video" button
- the user pastes the url in the field of a Vimeo video and clicks the "Import Video" button. If:
- the URL is of a public embeddable Vimeo video:
- they are redirected to the video asset create page.
- the video preview is visible on the asset create page.
- The user can add a transcript to the video.
- the URL has the domain vimeo.com but is not embeddable:
- an error is shown below the text field: "Please enter a valid video URL".
When a user views a Vimeo video added:
- the Vimeo video is embedded by the videosjs player.
- the transcript is shown using the standard transcript view.
- if the Vimeo video is not embeddable (e.g. because it has been deleted or embedding has been disabled) the player will show an error: "Video cannot be embedded."
Once the discovery and estimates are accepted by the client, the project enters the implementation phase.
To help everyone (including yourself) get a sense of where a project is at, add a timeline to the epic description.
- In the beginning stages of a project, the timeline can be fairly high-level. For example, it could just list the main phases of the project:
- Jan 2019: Discovery phase
- Feb 2019 -- April 2019: Implementation phase
- May 2019: Deployment phase
- June 2019: QA
- In the beginning stages of a project, the timeline can be fairly high-level. For example, it could just list the main phases of the project:
Note that for future reference it's helpful to mention all phases of the project, even ones that are already in the past at the time you create the timeline.
At any given stage of the project, the timeline for the next two sprints should be laid out in detail: Add the name of each sprint to the project phase that it belongs to, mentioning when it ends, and list the stories that are scheduled for it. Once all of the stories belonging to a given sprint are done, put a checkmark next to the name of the sprint. A good point in time to make these updates is towards the end of a sprint, when working on the epic update.
This format provides a concise overview of the project's status to anyone that might be looking at your epic.
If the scope/plan for the project changes significantly, try to keep the epic description field in Jira updated, so that it always has a useful and accurate explanation of the project, plan, timeline, etc.
- Look at epic updates as a service to yourself, not just to the person who is supposed to eventually read it, whoever that may be. It allows you a dedicated time to consolidate what is going on with the epic, to do any higher-level planning work, and to ask epic-level questions to your peers in the context of the update. It's one of the duties that at first may look to be a chore you just have to do as epic owner, but you and your epic can benefit tremendously from it just through a change in perspective. Spend the next epic update trying to really drill a little deeper, and you'd be surprised how much more of a handle you feel you have on it.
- If you are planning to go on vacation at some point over the course of the project, make sure to coordinate with your epic reviewer a few weeks ahead of time. If the project includes weekly stand-ups, your epic reviewer will need to be able to fill in for you at these meetings. This means that they will need to be familiar with the structure of the meetings, and that while you're away the meetings will need to happen at a time that is not in the middle of the night for them. So if necessary, make sure to move the meeting to a different time before you go on vacation. Let the client know when you will be away, and who will be filling in for you. Also, have the epic reviewer attend the last one or two meetings before you leave so they can meet the client and see first-hand what the structure of the meetings is like.
Day to day¶
At the start of your day, get an overview of all updates related to your epic. (You can log time spent on this on the epic itself.)
Create tasks for any urgent fires that might have come up and coordinate with the rest of the team to make sure they can be addressed right away.
In most cases your first point of contact should be the epic reviewer and/or other team members that already have context on the project. If they don't have time to address the fire, the next step will be to involve the sprint firefighters to see if they can help free up some time for the epic reviewer and/or other team members that already have context on the project and should ideally be working on the fire.
- Don't forget to notify the client that we are looking into whatever issue they reported.
- Determine priority for the remaining updates, relate them to existing tickets, and decide when to work on them.
At the end of this process you should be fully up-to-speed on the project's status, and it should be clear to you what aspects of the project (tasks, reviews, client communication) you'll need to work on that day. It should also help minimize interruptions throughout the rest of the day, allowing you to focus on completing the work that's on your agenda for the day.
Communicating Changes to the Group¶
As an epic owner, changes under your tasks may result in new features becoming available to the platform, or in new projects that may be of interest to the team at large. On previous occasions, discoveries have been in full swing only to find out another cell recently implemented the target feature.
To avoid such missteps, we have a two-step process for disseminating knowledge of new features. The first is that we use the ADR process, adding ADRs to repositories as decisions are made and explaining their reasoning.
When a new project is started or a new feature lands, go to the New Feature Announcement Thread and post a summary of the new feature or project, with a link to the relevant ADR, in a post. You're encouraged to include a video demonstrating the new feature if possible!
Guidelines to help communication with clients:
- When a client reaches out to you (via e-mail, Trello, JIRA, etc.), don't feel compelled to reply right away. Instead, take a moment to determine
- how important their request is relative to other work from the project that is currently in flight,
- whether the current sprint includes a task that the request is related to, and
- what the best way of addressing the request would be.
- We have a policy to respond to client requests within 24h, so unless you're dealing with something that needs to be addressed right away (such as a client's instance being down), it's perfectly fine to take some time to figure out the best way forward.
- Make sure to thank the client for any feedback that you get from them, even if it's negative. If necessary, apologize and admit mistakes, but mainly focus on finding a solution, and involve the client in the process of coming up with a solution as much as possible.
- Tailor the level of detail to your client and their interests. For example, if you're speaking to an operations specialist, it's ok to go into technical details about a change or question. But if you're speaking to a site manager, they may only want to know the benefits and risks of a change, not the technical details.
- If you need to receive sensitive information from a client (e.g. a SSO client ID and secret), ask them to use onetimesecret.com, and to send each part of the secure information using separate OTS links. Reference our security policy for more details.
Handling stuck tickets¶
Occasionally when supervising an epic, there will be a ticket that risks jeopardizing the epic. For whatever reason, the task is taking much longer than it should. This might be due to unforseen complexity, an assignee's lack of experience with the tools, Heisenbugs, or lack of aptitude for the task. Whatever the reason, as the epic owner, you must guard your budget and find a way to keep the task from sinking the epic.
The best approach is to take preventative measures. Keep close watch on tasks from your current epic in the sprint. Encourage your assignees to keep you up to date and to share code early. Be especially vigilant if the assignee is a newcomer. They sometimes get stuck and go quiet for fear that they may be disqualified for asking for help, or from being overwhelmed by the task. Proactive measures are always preferred over other options.
If it's clear that the current assignee isn't going to complete the ticket in a reasonable amount of time, consider if there's someone else who might be able to handle the task better. Check with the ticket reviewer and firefighters to see if there may be another approach. You may reassign a ticket if it will guard the budget. However when doing so, be sure to investigate what went wrong and talk with the assignee about it. Assignees are responsible for the work they take on. You may wish to talk with Xavier about the incident as it may require some additional training to prevent from happening again.
If the ticket appears to be a timesink regardless of who would take it, consider postponing the ticket until more information can be gathered. You may also talk with the client to verify/change the priority of the ticket. They might decide that the task being worked on isn't quite as important, if it is risking the whole project. Note that postponing should NOT be done in the case that upstreaming a change is taking longer than we'd like, and it should not be done if there is another way we can find to complete the task. Failure to complete a task can cause strain on our relationships with a client. If you take this route, be sure to detail why and what happened in your next epic update.
A note on newcomers with stuck tickets¶
Sometimes, the stuck ticket may be assigned to a newcomer and require reassignment. This requires careful consideration. Is the reason the ticket is stuck because of unexpected complexity, or other factors beyond the newcomer's control? If it is, you will want to communicate this to the newcomer and work with their mentor to find a new task for them to work on. After they are reassigned, perform a root cause analysis on how the ticket got assigned to a newcomer when it should not have been, include this in your next epic update for review.
However, if the work done by the newcomer is not up to standards, and a new assignee will have to redo it:
- Recreate the ticket and reassign it.
- Set the account of the old ticket to the newcomer's onboarding epic and the account to the recruitment account.
- Contact Xavier as their contract will need to be terminated.
- Send an email to dev@ detailing what happened, in response to the newcomer's review thread, and notify the newcomer's mentor.
Note: If the newcomer's work is still useful and the ticket is reassigned for other reasons than aptitude issues, you will need to keep the hours spent as part of the task, and work to complete it in the remaining budget. For this reason (and others), it is important to keep on top of communication for tickets assigned to newcomers.
The end of a project or client relationship is an opportunity to reflect on what went well, and what can be improved.
As part of completing your epic, be sure to schedule a task to write up your experiences and observations. Use the epic retrospective template to create a document for your epic, and link to it from your client's CRM entry.