Best way to document project configuration and changes

[Allen Chen]

Hello fellow Jira admins, 

I wonder what's the best practice to document/track project configurations for all of your projects (which includes workflow setup, automation, scripts used etc.). As there are more and more projects to manage, it would be great to have a place to document all the configuration changes and why certain project was set up this way. 

Any inputs are greatly appreciated. 

[Alvin Rodis]

Hi @Allen Chen - I have specific audiences in mind when I create documentation....whether it is an end-user turnover "functionality" doc or a technical doc that my team and I can come back to reference later.

Looking at a comprehensive structure of documentation of your instance (which I think you're asking about), this is a good format:

Structuring documentation for Jira configuration items can be crucial for understanding, maintaining, and scaling your Jira environment. Here’s a recommended structure that balances clarity and accessibility:

1. High-Level Overview

• Objective: Explain the purpose of each major component in Jira (e.g., Projects, Workflows, Schemes, Custom Fields, Asset Hierarchies).
• Scope: Define the scope of the documentation, stating what is and isn’t included (e.g., “This documentation covers configurations specific to Project A and shared schemes”).
• Audience: Specify who the documentation is intended for (e.g., Jira Admins, Project Leads, IT Support).

2. Configuration Items by Category

• Projects: List each project with an overview of its configurations, including:
  • Project key and name
  • Schemes in use (e.g., issue type scheme, permission scheme)
  • Responsible owner or team
• Issue Types and Schemes:
  • Outline each issue type scheme, workflow scheme, and any custom schemes.
  • Detail the issue types associated with each scheme and the projects using them.
• Custom Fields:
  • Document each custom field, including:
    • Field name and description
    • Field type (e.g., text, single select)
    • Projects or screens where it’s used
• Workflows:
  • Document each workflow and its schemes, including:
    • Statuses and transitions
    • Post-functions, conditions, and validators
    • Projects and issue types using the workflow
• Permissions and Roles:
  • Outline permission schemes and role configurations, including:
    • Scheme name
    • Assigned permissions
    • Associated projects or teams

3. Asset Hierarchies and Dependencies

• Include visual representations or lists that capture dependencies, like Suite, Product Area, and Issue Category levels.
• Describe the relationships and links between objects, especially if they use cascading fields or are critical to processes.

4. Automation Rules

• Document each automation rule, including:
  • Rule name and description
  • Trigger, conditions, and actions
  • Associated projects or issue types
  • Owner or responsible administrator

5. Naming Conventions and Standards

• Define naming conventions for schemes, workflows, and custom fields for consistency.
• Include a glossary or naming standard reference section.

6. Maintenance and Governance

• Provide guidelines for adding or updating configuration items.
• Outline the approval or review process for configuration changes.
• Define a regular audit schedule and responsible parties for updates.

7. Change Log

• Maintain a change log of configuration updates, including:
  • Date of change
  • Configuration item affected
  • Description of change
  • Approver or change owner

8. Appendices

• Include reference materials, such as:
  • Diagrams of workflows
  • Sample issue hierarchy diagrams
  • Links to Jira REST API for advanced users needing data extraction

[Susan Waldrip]

Nice list @Alvin Rodis! There is actually a 3rd-party app called Smart Jira Configuration that documents a lot of this with just a couple of clicks. It doesn't provide graphics, org charts, policy, etc. but it could document the project configuration part nicely and in great detail.

[Radka Svobodova]

We share the generic configuration and when there is a specific need of particular project for exceptional we create a coppy of generic configuration and name it by that project and to description we add information regarding the config change and the reason

and also we have a separate jira project to track requirements for specific jira configuration - so it can be found there, who, why , what and when :)

[Gil Hoffer]

Hi @Allen Chen ,

Gil from Salto here.

We have a lot of great experience with customers (typically of highly complex Jira cloud setups) automatically documenting their configs and changes to it in code in Git (and most of them would also tie these config changes to issues in a separate jira project to track jira requirements like @Radka Svobodova suggested).

Many of these customers moved from a manually created documentation scheme (as suggested by @Alvin Rodis ) to using us, as it ensures that the documentation is always up to date (as it gets auto generated from the actual jira sites).

Typically, this would be tied to a proper change management process done with Salto (e.g. all jira config changes first done in a sandbox, and then after review and proper gates are promoted to production), but some just use us for the documentation and visibility aspects.

If it sounds interesting, feel free to reach out.

[Shah, Piyush]

Re: "automatically documenting their configs and changes to it in code in Git (and most of them would also tie these config changes to issues in a separate jira project to track jira requirements"

• Is this supported with Atlassian Cloud?
• Is it blessed by Atlassian?
• Do you have a demo link for this to share? 

[Gil Hoffer]

@Shah, Piyush , yes it is supported with Atlassian Cloud and is blessed by Atlassian (and is on the marketplace).

There are quite a few demos at https://www.youtube.com/playlist?list=PLw8aI-Qt_EsZiK4aOeiL76wqntbnmoBI8 and pretty decent explanations at https://www.salto.io/solution/jira .

There's also a free trial (and a free tier), so you can just hook it up to your site (can also be a sandbox / dev instance) to get a feel for it.

[Aaron Morris]

@Allen Chen - For what it's worth, I'm a customer of Salto and vouch it works fantastic for this purpose.

I think the free version will basically satisfy your requirements, and the paid version definitely will.

It's worth investigating (IMO).

[Josh McManus]

Can confirm. I'm still working with my organization to get the budget allocated for the purchase, but based on what it offers for free and my time with the trial I am definitely a convert. I don't know how any decent-sized organization that cares about the health of their project data pipeline lives without the capabilities that Salto offers.

[David Foote]

A minor point, but consistent naming of workflows and automation will go a long way to figuring out which things go together.

Tagging automations has also been hugely helpful - especially when combined. Tag all change management rules, add additional tags for automations that deal with a specific type of change, or that call web endpoints, etc.

[Alvin Rodis]

@David Foote Tagging automations is the best. It has saved me tons of time!

[Tracy B]

Chiming in to agree here -- we ridiculously "overname" everything, all the way to "(division's) research project issue screen scheme" as we found it made things clearer when trying to set up new projects. 

Our lives have also been made somewhat simply by our use of Deep Clone add on and starting to limit ourselves to a smaller number of template projects. It was too hard to support the Wild West of many utterly unique projects.

[Josh McManus]

You're telling me "Copy of Copy of Unified ABC Workflow scheme w/Added Status no Bugs 2.0" isn't clear? ;)

[Shah, Piyush]

I follow what may be worded as "Optimal" documentation characterized by:

• Document Project Automation in the "Inline" Description.
• Document Field definitions as tooltips and this can be customized at project level, if needed
• Use intuitive names for custom entities (issue types, status, field names, etc.) so it reduces (if not eliminate) the burden on documentation
• I do document initial requirements in business language which may not be Jira language
• Enhancements are documented via the Jira tickets that provide what/why and the traceability
• Refer to Atlassian support and/or community links where possible
• Empower project admins to maintain their respective project config in the form of behavior and business rules. 
• No, this does not include maintaining table of fields, field attributes, transitions, screens, workflow rules.  Even if someone is claiming to maintain that I tend to refer to SSOT (single source of truth) and that is actual system configuration.
• Challenge is balancing ever-growing need for customizations against standardized process which at times may impede innovation.
• I wish ..... Atlassian had a way to package or version control changes so admins can quickly see who did what.  Makes it easier to debug, rollback, etc.  I am optimistic that they will have this soon or else someone else will ;-)

[Gil Hoffer]

These are very good guidelines.

As for the "I wish ..." bullet, @Shah, Piyush , this is exactly what we do at Salto... Feel free to DM me if you're curious (or just browse our web-site and/or youtube channel)

[Shah, Piyush]

@Gil Hoffer : I benefit a lot from Atlassian Community to actually find solutions to many challenges with Atlassian and I do NOT write endorsements like this very often.

I must say that, Salto is a life savior.  We are doing a trial and I want to publicly state that Salto is doing two most desired things:

• Reducing the time to deployment on an average from X to literally X/20.  Meaning this thing provides 20X productivity boost for deployments.
• And the quality of our work is improved since we don't have to manage long run-books and worry about carpel tunnel disease anymore.  

Seriously, the only regret I have is why did I wait 4 months to do the trial.

Lastly, Salto may NOT be perfect just like almost everything else but it has enough power and benefits that we can't live without.  And in the most ideal case, Atlassian should have this functionality built-in.

[Gregory Kneller]

Option 1. Use a Confluence Page for Each Project

• • Set up a dedicated Confluence page for each project to document its current configuration. This page should include all relevant details, such as workflows, issue types, custom fields, permissions, and automation rules. Use "Project Page" feature in project configuration and Connect to Confluence.
  • Having a single page per project makes it easy to understand the full configuration at a glance.

Option 2. Create a Jira Project for Change Requests

• Set Up a “Jira Configuration” Project:
  • Create a dedicated Jira project specifically to manage configuration change requests across all projects. Each configuration change request should be created as an issue in this project. This setup allows you to track the status of each request, define permissions and roles,  prioritize changes, and communicate with stakeholders more effectively.
    
    
• Example Custom Fields for Change Tracking:
  • Project Selector Field:
    • Create a custom field named "Project" to allow users to select the specific project they’re requesting changes for. This field will make it easier to filter and track requests by project.
    • Note: If you want this field to reflect all current projects automatically, you may need to use a scripting tool like ScriptRunner to populate it dynamically or update it manually as projects are added or removed.
  • Type of Change Field:
    • Add a custom field named "Change Type" with predefined options like:
      • Custom Field
      • Permissions
      • Workflow
      • Issue Type
      • Automation
      • Others
    • This field will help categorize each change request, making it easier to report on and manage changes based on the type of configuration being updated.

Combine Confluence Page and  the Jira Project

On the main Confluence page for each project, add a section that links to relevant change requests in the “Jira Configuration” project. This can be done by embedding a Jira filter macro that pulls in all issues tagged with that project.

Automate administrative task in workflow of the tracking project

 In addition to tracking change requests in a Jira project, you can also use automation and scripting tools (like ScriptRunner, Automation for Jira, or Power Scripts) to streamline the workflow by automating certain administrative tasks after a change request is approved. This can save time and reduce the potential for errors in repetitive administrative work.

Example: Set up a workflow for change requests that includes distinct stages such as:

Open → In Review → Approved → In Progress → Completed

When a change request reaches the Approved stage, an automated action can be triggered to implement certain types of changes directly and move to completed state automatically,  or notify the appropriate administrator to take action.

But I  am not sure that automation  may work in Jira Cloud due to strict permission concepts for scripts.

[Ravee]

We usually define a process around workflow setup, automation, scripts used etc. Then educate the "project leads" for individual projects within Jira.. And then let them manage it strictly. The process may vary from company to company depending the size and complexity of the projects. In a nutshell, since Jira is highly customizable, its always best to keep it as simple as possible for everyone to understand, follow, adapt the changes.