We’ve covered setting up a new project in parts one and two of this series. Now, let’s cover where you’ll spend most of your time in Jira. We’ll start with tickets because crafting them is an essential skill and where a lot of communication happens with team members.
The art of crafting a Jira ticket
Imagine each Jira ticket as a short story. The title is your headline - crisp, clear, and to the point, capturing the issue's essence. It should typically start with a verb.
- "Build location content type."
- "Configure the WYSIWYG editor."
- "Assign default metatags for Popular Topics."
Bugs should vary from tasks by specifying the who/what/where/how for a particular problem.
- "Links in related documents do not trigger a download."
- "Images in news list do not render."
- "Location nodes will not save after editing."
- "Editors can't filter document library."
The title should give someone enough context to understand what the ticket is asking for without opening it to read the description. People should be able to skim a list of ticket titles usefully.
Title tagging
While tickets can have labels, it’s often helpful to use a common tagging system in the ticket titles to visually group them when scanning the list. For example, tickets part of an Epic might have titles preceded by the Epic name in brackets or with a colon separator.
- Blog post: Build content type
- Blog post: Style default display mode
- [Metatags] Set sitewide defaults
- [NPR integration] Build proof of concept
But don’t overtag ticket titles. Add just enough context to separate them from other tickets. Overtagging titles can reduce the scannability of a list of tickets when all you see are the tags and can’t read enough of the actual ticket title.
Poor tagging:
- [Blog] [Content Type] [Build] Blog post content type
- [Blog] [Theming] [Display] Style default blog post display
Better tagging:
- Blog: Build post content type
- Blog: Style default post display
Writing Jira ticket descriptions
A well-written ticket description guides the reader (in this case, your team members) through the issue, offering context, background, and the scope of the problem or task. You're not just listing a problem; you're setting a scene and creating a shared understanding among your team.
Ticket descriptions in Jira should be clear and factual, including instructions, acceptance criteria, and essential context. Minimize references to external documents, but use screenshots for clarity. Link to related documents in the Epic and not in each ticket to avoid updating links frequently. Acknowledge uncertainties without lengthy discussions; handle requirement discussions in comments or external documents. Update descriptions with new decisions or facts but avoid significant changes once a ticket is in progress, as substantial requirement changes are better addressed in new tickets.
Description framework
Using a template ensures consistency and completeness. The suggested format includes:
- Overview - a high-level summary and the purpose of the ticket.
- Request - detailed description of the task.
- Acceptance Criteria - conditions for completion.
- Resources - links to related discussions or documents.
Add a fifth section for bug tickets: "Steps to Reproduce.” Detail the process of recreating the bug, supplemented with screenshots or recordings.
Poor description example:
Please add a new content type for blog posts. It should have a title, body, author, and date. Let me know if you have any questions.
Better description example:
Overview
We need a new "Blog Post" content type to allow editors to create and manage blog content.
Request
Please create a new "Blog Post" content type with the following fields:
- Title (text field, required)
- Body (long text field with WYSIWYG, required)
- Author (entity reference to User, required)
- Publish Date (date field, required)
Acceptance Criteria
- Content type is created with specified fields
- Editors can create, edit, and delete Blog Post nodes
- Blog Posts are displayed on the /blog listing page
- Individual Blog Posts are displayed at /blog/[title]
Resources
- Blog wireframes: [link]
- Blog requirements doc: [link]
The role of comments in Jira tickets
Comments in Jira tickets are your dialogue. They're the ongoing conversation about the ticket, where updates, clarifications, and collaborative problem-solving unfold. Effective use of comments keeps everyone in the loop, ensuring the ticket’s story is always current with the team’s collective wisdom.
Comments in Jira serve for conversational decision-making and as a paper trail for changes. They should include transient information like status changes, requirements questions, and implementation discussions.
Decisions reached in comments should be added to the ticket description.
Lengthy discussions, which require a lot of back and forth and involve multiple team members, are better suited to other documents or meetings. Comments should explain the 'why' behind changes like assignments or updates, aiding clarity over time. It's important to respond to mentions in comments to avoid work delays. Using email filters and Slack notifications can help manage these mentions effectively.
Poor comment:
I finished the blog content type. It's ready for review.
Better comment:
I completed the following for the new Blog Post content type:
- Created content type with Title, Body, Author, Publish Date fields
- Configured permissions for editors to manage Blog Posts
- Set up /blog listing and individual post pages
It's ready for review. Please take a look and let me know if any changes are needed before moving to UAT.
Closing a Jira ticket
Closing a Jira ticket should feel satisfying. It is the mark of a completed job. But remember, the end of one ticket is often the beginning of another, as projects are a continuous narrative of challenges, learning, and achievements.
In Jira, defining "Done" involves using multiple statuses within the Done category to accurately track work progress while utilizing reporting tools. These statuses can include names like User Acceptance Testing (UAT), Merged, On Stage, Ready to Deploy, Deployed to Prod, and Done, each with specific meanings.
It's crucial to communicate these definitions clearly to stakeholders to avoid confusion, as tickets in the Done category might appear finished even though they haven’t been deployed to production. A recommended practice is to use the Fix Version field for clarity on deployment schedules.
Now, let’s talk about where most of these tickets come from. The issue schema is where we organize everything into Epics, Stories, and Tasks.
The Issue Schema
The issue schema in Jira is the backbone of your project management, organizing work into different types of issues such as Epics, Stories, Tasks, Bugs, Features, and Technical Debt. Each type serves a specific purpose and helps structure the workflow efficiently.
Epics: The Big Picture
Epics in Jira are like chapters in your project's story. They represent large bodies of work that can be broken down into smaller, manageable pieces. For instance, an epic might be "Redesign User Dashboard," which encompasses multiple stories and tasks.
When to use Epics:
- When you have a large project or feature that needs to be broken down into smaller parts.
- To group related stories and tasks under a common theme or goal.
- To track progress on major milestones or deliverables.
How to use Epics effectively:
- Define a clear "definition of done" for each epic.
- Use epics to provide context and high-level overviews, linking to detailed tickets for specifics.
- Regularly review and update epics to reflect the current state of the project.
Stories: User-Centric Narratives
Stories are more specific than epics and focus on delivering value to the end-user. They are individual user-centric narratives that describe a feature or functionality from the user's perspective.
When to use Stories:
- To capture user requirements and functionality.
- For tasks that deliver a specific piece of value to the user.
- When you need to break down an epic into smaller, actionable items.
How to use Stories effectively:
- Write stories in a 'verb the noun' format, forming imperative sentences like "Create the event content type."
- Use acceptance criteria to define the conditions for completion.
- Break down stories into smaller tasks if they become too large or complex.
Tasks: The Building Blocks
Tasks represent individual pieces of work that need to be completed, which may not necessarily deliver direct value to the user but are essential for the project's progress.
When to use Tasks:
- For work that needs to be done but doesn't fit into a story or bug.
- For internal or technical work that supports the overall project.
- When you need to track progress on specific activities or deliverables.
How to use Tasks effectively:
- Clearly define the scope and requirements for each task.
- Use subtasks to break down complex tasks into smaller, manageable pieces.
- Assign tasks to team members with the appropriate skills and expertise.
Bugs: Fixing Issues
Bugs represent problems or defects in the system that need to be fixed. They are crucial for maintaining the quality and stability of the project.
When to use Bugs:
- To report and track defects or issues in the system.
- For problems that need to be fixed to ensure the system works as expected.
- When you need to prioritize and manage the resolution of issues.
How to use Bugs effectively:
- Provide clear and detailed steps to reproduce the issue.
- Use screenshots or recordings to illustrate the problem.
- Prioritize bugs based on their impact and severity.
By understanding and effectively using each issue type in Jira, you can create a well-structured and organized workflow that supports your project's goals and ensures smooth progress toward completion.
Weaving the narrative of structured tasks
Every schema component contributes to the overall narrative's coherence, ensuring seamless progression towards the desired outcome. Aligning these elements according to your project's pace and team's work style is crucial. How you communicate your work to each other is just as important as the work itself, the lubrication of the engine, so invest in organizing your epics, stories, tasks, and tickets properly.