Documenting your JIRA project

Pages of documentation

I’m a big fan of good documentation because it:

  1. Protects my employer against the Mac Truck Theory.
  2. Saves me from the pain of forgetting something important.
  3. Helps everyone involved understand how all the pieces fit together to achieve their desired end result.
  4. Ensures the Quality Assurance team knows what to test.

I create a set of documents (Wiki pages) when I start the design of a new JIRA project. They are created from custom space templates that contain instructions for using each document and tables in which to place the “specs.” As the design sessions get underway, the documents are fleshed out and eventually presented to the project sponsor for approval.

Some documents listed below, such as Scripts, may not be needed for all projects. If that is the case, the page can either be removed or marked as “not applicable” with an explicit statement to that effect.

Main Page

The main page is a table that lists all the other pages in the documentation set. By using each column as a checklist of sorts, it offers a quick way to assess where you’re at in the design process. It also includes a place for sign-offs to be collected.

The documents are shown in the order in which I recommend discussing them. Each one builds on the previous one.

ItemDiscussedAll Action Items Complete?Data/Person Providing Sign-off?Ready to be Developed?Development Complete?
Open IssuesA checkmarkA checkmark2016-01-14/JohnA checkmarkA checkmark
Project OverviewA checkmarkA checkmark2016-01-14/JohnA checkmarkA checkmark
Groups and RolesA checkmarkA checkmark2016-01-15/JohnA checkmarkAn illuminated Lightbulb
Field MappingA checkmarkAn illuminated LightbulbA red XA red X
WorkflowA checkmarkA checkmark2016-01-20/JohnA checkmarkA red X
TransitionsA checkmarkAn illuminated LightbulbA red XA red X
Issue Operation ScreensA checkmarkA checkmark2016-01-20/JohnA checkmarkA red X
Transition ScreensA checkmarkA checkmark2016-01-20/JohnA checkmarkA red X
PermissionsA checkmarkA checkmark2016-01-21/JohnA checkmarkA red X
EventsA checkmarkA checkmark2016-01-22/JohnA checkmarkA red X
NotificationsA checkmarkA checkmarkA red XA red X
Issue SecurityAn illuminated LightbulbA red XA red XA red X
FiltersAn illuminated LightbulbA red XA red XA red X
DashboardsA red XA red XA red XA red X
ScriptsAn unlit LightbulbAn unlit LightbulbAn unlit LightbulbAn unlit Lightbulb
Plugin RequirementsAn unlit LightbulbAn unlit LightbulbAn unlit LightbulbAn unlit Lightbulb

Project Overview

This page describes the new JIRA project being requested. It documents why the project is needed and its high-level configuration requirements. It also contains information to understand how the project should be delivered.

QuestionAnswer
What do you want to use as the name for this project?Digital Project Management
What is the business purpose for this project?Used to track all digital projects
What 3-6 character prefix do you want to use on issues created in this project? (It must be alphabetical)DPM
What is the full name of the person who will serve as the Project Lead of this project?John Parkinson
Which departments/business functions will be using the new project?Production, Technology, UX, Creative, and Account Management
What Issue Types do you anticipate using in this project? (Options include: New Feature, Improvement, Epic, Story, Task, Bug, and Sub-task)Content Updates, Maintenance, Digital Display, New Website Build, Design Refresh, SEO Task, Analytics Task, Content Task, and Template Task
What Resolutions will this project use? (This describes why and how an issue was closed. Options include: Done, Won't Do, Duplicate, Cannot Reproduce)Done, Won't Do
What Components will be used by the project? (Components are optional sub-sections of a project, used to group issues within a project into smaller parts.)NA
Are there any 'hard dates' driving the implementation of this project?No
Who will be involved in the design of the project, and how would you describe their prior experience with JIRA?John Parkinson, very experienced with JIRA; Maddie Gaston, new to JIRA; Steve Newell, JIRA Administrator;
Who will perform the User Acceptance Testing of your project, and have they ever tested a JIRA project before?John Parkinson, Maddie Gaston, Greg Nelson, Alexa Harrison

Groups and Roles

This document contains 2 tables that describe the Groups and/or Project Roles the project will use. Use color-coding or Confluence’s Status macro to flag anything new that must be created.

Group NamePurpose/DescriptionIs this a New Group?User(s) who should be members
DPM-QAQuality Assurance for digital projectsYesGreg Nelson, Alexa Harrison, Eric Clinton
DPM-ProjectMgmtProject managers for digital projectsYesGreg Nelson, Marianne Wilkens, Ralph Jacobs
Role NameIs this a new Project Role?Purpose/DescriptionUser(s) who should be membersGroup(s) who should be members
AdministratorsNoPeople who can administer the projectJohn Parkinsonjira-administrators group
DevelopersNoPeople who can log work on issues within the projectjira-developers group
QAYesPeople responsible for Quality AssuranceDPM-QA
UsersNoPeople who can view and transition issues in the projectjira-core-users group
Project MangersYesProject managersDPM-ProjectMgmt

Field Mapping

This document describes the fields that will be used by the project. This document becomes a guide to the custom fields, Field Configurations and Field Configuration Schemes that will be built in JIRA.

I usually list each built-in field (Reporter, Due Date, Component/s, etc.), but format it as struckthrough text if the field won’t be used for the project. This shows that the field was indeed discussed but then determined to not be needed.

I highlight any custom fields that will created specifically for this project’s use. I also indicate if a particular renderer will be used for a field, as well as whether the workflow programmatically will set a field (typically via a workflow post-function).

JIRA FIeldDescriptionField TypeRendererRulesDefault ValueNotes
AssigneeUser Picker
Component/sSelect List (multiple choices)Autocomplete Renderer
DescriptionA thorough description of the issueText Field (multi-line)Wiki Style Renderer

Environment

SummaryA brief description of the issueText Field (single line)
Business CasePlease provide background information and/or rationale relevant to the submission of this request.Text Field (multi-line)Wiki Style Renderer
Project Approval DateIndicates the date the project was approved by the steering committeeDate PickerDefaults to current date (via a script)Need to confirm with business owner that this is actually needed.
FrequencyIndicates how often reviews will be conducted.Select List (single choice)Value values are:
Daily, Weekly, Monthly
Weekly

Workflows

This documentation is simple. It just contains the workflow chart(s) that the project will use.

Issue Operation Screens

This documentation describes each screen used to view, create, or edit issues.

On each screen, fields are listed in the order in which they appear on the screen. A yellow star is used to highlight fields that must be supplied when the issue is created.

If the screen uses multiple tabs, then the tab name is shown in red.

All Fields Available to the ProjectCreate screenView/Edit screen

  • Built-in FIelds


    • Summary

    • Description

    • Priority

    • Component/s

    • Due Date

    • Assignee

    • Attachments

    • Reporter


  • Custom Fields


    • Business Case

    • Project Approval Date

    • Frequency

  • SummaryA yellow star

  • PriorityA yellow star

  • Description

  • Business CaseA yellow star

  • Due DateA yellow star

Main Info



  • Summary

  • Priority

  • Assignee

  • Description

  • Component/s


Secondary Fields



  • Business Case

  • Due Date

  • Project Approval Date

  • Frequency

Transition Screens

This documentation describes each screen that will be displayed as the user transitions an issue through its workflow. used to view, create, or edit issues. Screens are shown using the same ‘designator’ (like S1, S2, etc.) as shown on the workflow chart.

I like to name transition screens with a prefix of “Transition: ” to make it clear they could be used by multiple projects. If possible, I also name them in a way that indicates the fields that are shown. For example, a screen that is used to assign an issue and log work against the issue might be named “Transition: Assign & Log Work.” This may seem like overkill, but it really helps when you’re trying to see if you can re-use an existing screen for some new project you’re designing.

The fields are shown in the order in which they appear on the screen. Fields that must be supplied during the transition are marked with a yellow star.

All Available FieldsTransition: Assign screen (S1)Transition: Approve screen (S2)

  • Built-in FIelds


    • Summary

    • Description

    • Priority

    • Component/s

    • Due Date

    • Assignee

    • Attachments

    • Reporter


  • Custom Fields


    • Business Case

    • Project Approval Date

    • Frequency



  • Assignee
  • Project Approval DateA yellow star

  • Due Date

  • Business Case

  • Frequency
  • Permissions

    This page basically mirrors JIRA’s Permission Scheme screen which lists each possible permission. For each, it lists the users, groups or roles that will be granted that permission.

    Project PermissionDescriptionGrant this Permission to...Notes
    Administer ProjectsAbility to administer a project in JIRA.Administrators project role
    Browse ProjectsAbility to browse projects and the issues within them.Application Role (Any logged in user)
    View Read-Only WorkflowUsers with this permission may view a read-only version of a workflow.Application Role (Any logged in user)
    Assignable UserUsers with this permission may be assigned to issuesUsers project role

    Events

    As you may know, a custom event may be needed because no standard event contains the content you want to appear in a notification. It may also be needed to ensure that the correct recipients get notified.

    For example, the “Issue Updated event” may be triggered at many times during your workflow as well as when the user initiates a Issue Operation, and perhaps the recipients of such notifications are the same except for one particular scenario. In that case, I’d set up a new custom event that is identical to the Issue Updated event except for its name. In the Notification Scheme, though, the Issue Updated event would reflect a different recipient list than my new custom event.

    Event NameIs this a new Event?Email Template on which it is Based...Customization(s) needed to Email Template
    Project Canceled eventYesIssue Closed

    Notifications

    This documentation lists each Event that could be triggered via the workflow, as well as Issue Operations like adding a comment or assigning an issue.  The desired recipient(s) are listed for each Event. It builds on the Events documentation, as well as the Groups and Roles documentation.

    Event NameEvent Type (e.g., System or Custom)DescriptionNotes
    Issue CreatedSystemAn issue has been entered into the system.Current Assignee,
    Reporter
    Issue UpdatedSystemAn issue has had its details changed. This includes the deletion of an issue comment.Current Assignee, Reporter, All Watchers
    Issue AssignedSystemAn issue has been assigned to a new user.Current Assignee, Reporter, All Watchers
    Issue ResolvedSystemAn issue has been resolved (usually after being worked on and fixed)Current Assignee, Reporter, All Watchers
    Project Canceled eventCustomReporter, All Watchers

    Issue Security

    If the project will be using Issue Security, this documentation describes each security level that will used.

    Name, as it is to appear on the screenDescriptionMembersSet as default?
    Only Project Management TeamProject management team onlyMembers of the DPM-ProjectMgmt groupNo

    Filters

    This documentation describes the filters that will be used by gadgets on the project’s dashboard(s) or via subscriptions for reporting purposes.

    During the design work sessions, I flesh out the business requirements and fill in most of the columns shown below. The Filter ID and JQL columns would be supplied during actual development.

    Filter NameFilter IDPurpose (in English)JQLFields in ResultsetSort Sequence for ResultsetOwner of FilterShared With
    Tasks starting in a week10814Identifies tasks with a start date within the next 7 daysproject = "Digital Project Management" AND status! = Done AND "Start date" > now() AND "Start date" <= 7dIssue Type, Summary, Reporter, Assignee, Start Date, Due Date, StatusStart Date, StatusJohn ParkinsonAnyone with a role on the Digital Project Management project
    Overdue Tasks10815Identifies tasks that are overdueproject = "Digital Project Management" AND status! = Done AND "Due date" < now()Issue Type, Summary, Reporter, Assignee, Start Date, Due Date, StatusDue Date, StatusJohn ParkinsonAnyone with a role on the Digital Project Management project
    Unresolved DPM issues10816Identifies issues in the DPM project with no Resolution setproject = "Digital Project Management" AND resolution IS EMPTYIssue Type, Summary, Reporter, Assignee, Start Date, Due Date, Status, ResolutionKeyJohn ParkinsonAnyone with a role on the Digital Project Management project
    Resolved DPM issues10820Identifies issues in the DPM project that have been resolvedproject = "Digital Project Management" AND resolution IS NOT EMPTYIssue Type, Summary, Reporter, Assignee, Start Date, Due Date, Status, ResolutionKeyJohn ParkinsonAnyone with a role on the Digital Project Management project

    Dashboards

    This documentation describes each dashboard that will be used by the project. Often a project will have 2 dashboards: one oriented for the people submitting the issues, and another oriented for the people working on the issues. In some cases, it may be desirable to run a Groovy script to “push out” the dashboard to its intended audience, rather than require each user to ‘favorite’ the dashboard.

    Dashboard NameAudiencePushed Out To...# of Columns in LayoutColumn1 ContentsColumn2 ContentsColumn3 Contents
    DPM MgmtProject managers of projects tracked in the DPM Digital Projects projectYes2Filter Results gadget:

    • Filter: Tasks starting in a week

    • Number of results: 10

    • Fields to Display: Issue Type, Key, Summary, Assignee, Start Date, Status

    • Refresh interval: Every 15 minutes

    Filter Results gadget:

    • Filter: Overdue Tasks

    • Number of results: 10

    • Fields to Display: Issue Type, Key, Summary, Assignee, Due Date, Status

    • Refresh interval: Every 15 minutes

    DPM TeamAnyone involved with the DPM Digital Projects projectNo3
    • Assigned to Me gadget:


      • Filter: Tasks starting in a week

      • Number of results: 10

      • Fields to Display: Issue Type, Key, Summary, Priority, Due Date, Status

      • Refresh interval: Every 15 minutes>

    • Projects gadget:


      • Projects and Categories: Projects

      • View: Brief

      • Number of Columns: 1

      • Refresh interval: Never

    Two-Dimensional Filter Statistics gadget:

    • Filter: Unresolved DPM issues

    • XAxis: Assignee

    • YAxis: Issue Type

    • Sort Direction: Ascending

    • Number of Results: 10

    • Auto refresh: False

    Activity Stream gadget:

    • Global Filter: Project = DPM

    • Available Streams: select all

    • Limit to: 20

    • Automatically refresh this activity steam: Every 15 minutes

    Scripts

    This page describes the scripts that will be invoked to extend native JIRA functionality. These leverage Adaptavist’s awesome ScriptRunner for JIRA add-on and are typically written in Groovy. Scripts can be used in workflow conditions, validators or post functions.

    You can also list any Javascript scripts you use here too. One use case for these is to set a default value for a field before a transition screen is displayed.

    ItemDescription
    Script Name:DPM_SetDefaultQAssignee.groovy
    Script Language:Groovy
    When invoked:As a post function during the following workflow transition:

    • Create issue

    Purpose:Set QA Assignee to the first user that's a member of the QA project role.
    File Path on server:/opt/gt/gthome/groovyscripts/DPM_SetDefaultQAAssignee.groovy
    Source Code:

    package com.example.jira.scripts.groovy
    import com.atlassian.jira.issue.util.DefaultIssueChangeHolder
    import com.atlassian.jira.issue.util.IssueChangeHolder
    import com.atlassian.jira.ComponentManager
    import com.atlassian.jira.issue.CustomFieldManager
    import com.atlassian.jira.issue.IssueManager
    import com.atlassian.jira.issue.fields.CustomField
    import com.atlassian.jira.issue.MutableIssue
    import org.apache.log4j.Category
    import com.atlassian.jira.project.Project;
    ...

    Add-on Requirements

    This page describes any add-on that will need to be installed (and possibly purchased) to support the project’s requirements.

    Before introducing a new add-on to your JIRA instance, it should be thoroughly evaluated in a non-Production environment to ensure it provides the desired functionality and “plays nicely” with other installed add-ons.

    Add-on Name, including a link to the plugin on Atlassian MarketplaceStatus
    (A question mark=May Use; A checkmark=Will Use; A red X=Won't Use)
    Add-on Version to be InstalledWhy is this Add-on Needed?Add-on License
    ScriptRunner for JIRAA checkmark4.2.0.5To support scripts for the project requirements that cannot be met with native JIRA functionality.ACCBQQ0ODAoPeNqVUM1LwzAUv+evCHiUlnZsTgcBZ9eDsA/RqRcvb/F1DaZpeEmG/e9Nt05kN0Nye

    Pk9fl9X2zrwFXQ8m/JsMhvfzfKcF4stH2X5hC3QSVLWq9aIufcg6waN588oO6mReNUSL1pT6YBG4

    uWYZ/Fc81eH5D5mEWkaJKlA86WSaByydWh2SJvquCKSnBWE0KstwKPoLSRZvFMWWaO6X0OD4gG96

    /g76C+kM1CuQGmx65F7sLZShKlsG1YeQIcjo6hAR8X4mfoarQ57ZSy2VveLpkrhN15CQ7w0EqsDC

    k8BmT5ZfotGe7YRi4rGo4GYtPy2irqz55vB87+k4oBkSblBbkN7MMqdrM9PidhLuRbxJZMsG49uc

    zbU+Ec+GK0a5fHzjG07i8fWis1qVT4Xj/Mlewoka3B4WfIPPtm2SjAsAhReNQX3YjTP/jaK/bPNJ

    IL8ng8wEgIUGYWts9W1Mm9SmvHIhpi7FssfK3c=X02f4

    Conclusion

    This post was originally published in 2012 and has continued to evolve the more I use it.

    I’m interested to know your thoughts about the sort of JIRA project documentation you’ve found to be helpful. Please share in the comments!

    ,

    4 Responses to Documenting your JIRA project

    1. Dan Dunleavy April 24, 2012 at 9:50 am #

      Fantastic job on this article. For someone new looking to implement JIRA, you provided a wealth of information.

    2. Saneth Kumar June 12, 2012 at 2:34 am #

      Hi Betsy,

      Very helpful post! I’m in the middle of handing over a project to another team and this has really helped me organize my documentation.

      Thank you 🙂

      Best,
      Saneth

      • Dipti Ranjan Behera August 14, 2012 at 6:46 am #

        Hi Betsy,

        This is an excellent and total documentation of things required for a project setup.

        BR,

        Dipti Ranjan

    3. Dina May 31, 2013 at 10:06 am #

      Great article, thanks!! I am in the very early stages of converting a marketing department to systematized project management and this will be very helpful as we define and develop our project documentation. I really appreciate your blog.

    Leave a Reply

    Simple Share ButtonsShare:
    Simple Share Buttons