Documenting Jira projects is underestimated, yet necessary if you’re managing complex use cases and multiple teams.

While its value might not immediately seem clear, it becomes so over time: when an administrator leaves, when they have to transfer their work, or a new project, full of arcane configuration, is to be migrated on production.

This article aims to introduce you to documenting projects efficiently using best practices, saving you time in the process.

‍

‍

‍

‍

‍Why Document?

If documentation is so crucial, why isn’t everyone doing it? The problem is usually:

• The required time investment
• The required costs
• A lack of standardization
• The scope of the documentation

However, without it, this happens:

• The work cannot be transferred
• Bus factor
• Difficulty in cleaning up Jira
• No manual
• User confusion and refusals to work in the tool
• A lack of governance

These might require a lot of work later or become blockers – for reasons documenting was refused in the first place. The required time and costs will pay off, however, when you compare them to a new administrator re-reading every project’s settings just to understand how they work.

Imagine this happening on a 100+ project instance – which actually isn’t that unusual. Documenting works best when proper governance practices are already in place, such as a small number of administrators and a dedicated project used for changes. That’s because nobody else will change the documented settings, except for the administrators.

Lastly, you don’t need to document everything or nothing. Documenting in small bits over time (e. g. one or two projects per month) is certainly better than nothing. Start with the most complex projects first.

But first... a Project List!

You might be thinking: Fine, I’ll document! But where to start? And how should it look?

Start simply. List all of your Jira projects and write down their important settings. For starters:

• What is the Project name?
• What is its abbreviation?
• Who is its Project Lead?
• How many issues are created monthly?
• What is happening in the project?
• How long will the project be used for?
• Does it contain any sensitive data?
• What is the Jira ticket in which the project was requested?
• Has this project become unused? Should it be archived?
• Special access permissions
• Other notes

Create this list so your admins can access it and modify it as projects change. Create it in Confluence, as it’s related to Jira, in your Administrators‘ space. For example:

By completing the project list, you have already done a great deal of work: by having a summary of what’s happening in your Jira, you’re prepared for e. g. identifying relevant stakeholders, future archiving opportunities, permissions management, sensitive data auditing, and other similar operations.

Next, let’s document the projects themselves. Under the list, create another page per project, resulting in a page tree. In the example, we have a documentation of the AS and EXD projects under the „Jira Projects documentation“ page:

And what should be here? Everything project related: the purpose of the project, the main stakeholders, but also the used schemes and their parts, so that non-admin users understand what’s happening in their projects and admins can learn quickly how is the project configured. And while a full-fledged project record might not apply for Next-gen projects, it’s very useful for the rest.

Writing out all of this manually would take a while, and while it would be worth it, there’s an app that will help you save a lot of time.

Introducing Glass

Glass (or Glass Project Documentation for Jira) is a Jira app that automatically creates, updates, and exports Jira documentation.

Its main strengths lie in:

• Documenting projects to save the time you would spend writing it, including constantly changing data, like involved users and number of issues.
• Recording every project in detail, down to e. g. each workflow condition, validator or post function
• Updating and reloading documentation so you don’t have to rewrite it manually
• Exporting it into Confluence

And how it’s done? Let’s review it.

Glass automatically records all projects on the Jira instance it’s installed on. You can view the documentation from the project’s navigational panel.

The first screen puts everything found under „Summary“ and „Details“ in one place, including the list of schemes, components and versions.

On the next page, you see the project’s workflow documentation: you select an issue type from the project list and get a workflow summary.

Underneath the workflow, you will see all of its transitions, including their conditions, validators and post functions, instantly accessible from the view, including all of the project’s screens and fields and what they do, again, without the need to delve into the project settings deeply.

Very similar views are used for a „People“ section, which displays users in each of the roles, and permissions and notifications settings.

It’s clear that Glass saves you a lot of clicking around in regular settings just to write everything down. You view the objects in a responsive interface that doesn’t make you wait for it to load each section. Its true strength, however, lies in its export option.

You can export your project settings to either a PDF or into Confluence, effectively creating a documentation page you can return to later. And, whenever you change something in the project, you can then update your report from Glass without having to rewrite it manually.

Closing words

Documentation of your Jira projects benefits you, your fellow admins and other users using Jira in the long run. Having at least a list of your projects with relevant data, operating along a reliable change management process will is guaranteed to save a lot of head scratching later.

As for an in-depth project analysis, while recording it certainly takes time, it doesn’t have to be a drudge: Glass will create detailed documentation for you and save it on Confluence for others to see. Try its trial version on Data Center or Server Jira deployments for 30 days for free – the Cloud version will arrive on the Atlassian Marketplace soon.

Business vector created by jcomp - www.freepik.com
Designed by katemangostar / Freepik