I’m a big fan of good documentation because it:
- Protects my employer against the Mac Truck Theory.
- Saves me from the pain of forgetting something important.
- Helps everyone involved understand how all the pieces fit together to achieve their desired end result.
- 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.
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.
|Item||Discussed||All Action Items Complete?||Data/Person Providing Sign-off?||Ready to be Developed?||Development Complete?|
|Groups and Roles||2016-01-15/John|
|Issue Operation Screens||2016-01-20/John|
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.
|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 Name||Purpose/Description||Is this a New Group?||User(s) who should be members|
|DPM-QA||Quality Assurance for digital projects||Yes||Greg Nelson, Alexa Harrison, Eric Clinton|
|DPM-ProjectMgmt||Project managers for digital projects||Yes||Greg Nelson, Marianne Wilkens, Ralph Jacobs|
|Role Name||Is this a new Project Role?||Purpose/Description||User(s) who should be members||Group(s) who should be members|
|Administrators||No||People who can administer the project||John Parkinson||jira-administrators group|
|Developers||No||People who can log work on issues within the project||jira-developers group|
|QA||Yes||People responsible for Quality Assurance||DPM-QA|
|Users||No||People who can view and transition issues in the project||jira-core-users group|
|Project Mangers||Yes||Project managers||DPM-ProjectMgmt|
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 FIeld||Description||Field Type||Renderer||Rules||Default Value||Notes|
|Component/s||Select List (multiple choices)||Autocomplete Renderer|
|Description||A thorough description of the issue||Text Field (multi-line)||Wiki Style Renderer|
|Summary||A brief description of the issue||Text Field (single line)|
|Business Case||Please provide background information and/or rationale relevant to the submission of this request.||Text Field (multi-line)||Wiki Style Renderer|
|Project Approval Date||Indicates the date the project was approved by the steering committee||Date Picker||Defaults to current date (via a script)||Need to confirm with business owner that this is actually needed.|
|Frequency||Indicates how often reviews will be conducted.||Select List (single choice)||Value values are:|
Daily, Weekly, Monthly
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 Project||Create screen||View/Edit screen|
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 Fields||Transition: Assign screen (S1)||Transition: Approve screen (S2)|
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 Permission||Description||Grant this Permission to...||Notes|
|Administer Projects||Ability to administer a project in JIRA.||Administrators project role|
|Browse Projects||Ability to browse projects and the issues within them.||Application Role (Any logged in user)|
|View Read-Only Workflow||Users with this permission may view a read-only version of a workflow.||Application Role (Any logged in user)|
|Assignable User||Users with this permission may be assigned to issues||Users project role|
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 Name||Is this a new Event?||Email Template on which it is Based...||Customization(s) needed to Email Template|
|Project Canceled event||Yes||Issue Closed|
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 Name||Event Type (e.g., System or Custom)||Description||Notes|
|Issue Created||System||An issue has been entered into the system.||Current Assignee,
|Issue Updated||System||An issue has had its details changed. This includes the deletion of an issue comment.||Current Assignee, Reporter, All Watchers|
|Issue Assigned||System||An issue has been assigned to a new user.||Current Assignee, Reporter, All Watchers|
|Issue Resolved||System||An issue has been resolved (usually after being worked on and fixed)||Current Assignee, Reporter, All Watchers|
|Project Canceled event||Custom||Reporter, All Watchers|
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 screen||Description||Members||Set as default?|
|Only Project Management Team||Project management team only||Members of the DPM-ProjectMgmt group||No|
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 Name||Filter ID||Purpose (in English)||JQL||Fields in Resultset||Sort Sequence for Resultset||Owner of Filter||Shared With|
|Tasks starting in a week||10814||Identifies tasks with a start date within the next 7 days||project = "Digital Project Management" AND status! = Done AND "Start date" > now() AND "Start date" <= 7d||Issue Type, Summary, Reporter, Assignee, Start Date, Due Date, Status||Start Date, Status||John Parkinson||Anyone with a role on the Digital Project Management project|
|Overdue Tasks||10815||Identifies tasks that are overdue||project = "Digital Project Management" AND status! = Done AND "Due date" < now()||Issue Type, Summary, Reporter, Assignee, Start Date, Due Date, Status||Due Date, Status||John Parkinson||Anyone with a role on the Digital Project Management project|
|Unresolved DPM issues||10816||Identifies issues in the DPM project with no Resolution set||project = "Digital Project Management" AND resolution IS EMPTY||Issue Type, Summary, Reporter, Assignee, Start Date, Due Date, Status, Resolution||Key||John Parkinson||Anyone with a role on the Digital Project Management project|
|Resolved DPM issues||10820||Identifies issues in the DPM project that have been resolved||project = "Digital Project Management" AND resolution IS NOT EMPTY||Issue Type, Summary, Reporter, Assignee, Start Date, Due Date, Status, Resolution||Key||John Parkinson||Anyone with a role on the Digital Project Management project|
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 Name||Audience||Pushed Out To...||# of Columns in Layout||Column1 Contents||Column2 Contents||Column3 Contents|
|DPM Mgmt||Project managers of projects tracked in the DPM Digital Projects project||Yes||2||Filter Results gadget:||Filter Results gadget:|
|DPM Team||Anyone involved with the DPM Digital Projects project||No||3||Two-Dimensional Filter Statistics gadget:||Activity Stream gadget:
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.
|When invoked:||As a post function during the following workflow transition:
|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|
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 Marketplace||Status|
(=May Use; =Will Use; =Won't Use)
|Add-on Version to be Installed||Why is this Add-on Needed?||Add-on License|
|ScriptRunner for JIRA||126.96.36.199||To support scripts for the project requirements that cannot be met with native JIRA functionality.||ACCBQQ0ODAoPeNqVUM1LwzAUv+evCHiUlnZsTgcBZ9eDsA/RqRcvb/F1DaZpeEmG/e9Nt05kN0Nye
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!