How to document Jira projects easily

Published:
Updated:
How to document Jira projects easily

This post was last updated more than 1 year ago. Some content may be out of date.

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

Author

Ákos Orosz
DevOps engineer

Author

Patrick Bakos
Test automation engineer

Author

Gabriella Keserű
Atlassian Consultant

Author

Zalán Balhási
Presales Engineer

Author

Thorsten Letschert
Product Marketing Manager at Decadis

Author

Gizem Gökçe
Atlassian Apps Manager at OBSS

Author

Evita Legzdiņa
Marketing Manager at eazyBI

Author

Zoltán Szentesi
Agile Coach

Author

Beatriz Biscaia
Content Marketing Specialist at Xray

Author

Jay Prakash
Senior Product Marketing Manager at Upscale

Author

Danut Manda
Co-founder & CEO at StonikByte

Author

Richard Birks
Senior Product Marketing Manager at ScriptRunner

Author

Yuri Kudyn
Co-founder of Release Management Apps and Journy.io

Author

John David Adler
Atlassian Consultant

Author

Csomós László
Senior Engineering Manager, GSBS Atlassian Team

Author

Tibor Mozsik
Head of Marketing

Author

Velizar Borisov
Atlassian Community Leader

Author

Julia Skoursky
Refine

Author

Claudia Kecskés
Senior Marketing Specialist

Author

Ármin Kubik
Backoffice team leader

Author

Csaba Geiszt
Software Engineer

Author

Amadea Kecskés D.
Sales Development Representative

Author

Endre Tuboly
Atlassian Consultant

Author

Bogi Pilinger
Backoffice Trainee

Author

Richárd Hevesi
Software Engineer

Author

Anna Nagyné Széles
Atlassian Consultant

Author

Lorena Santana Somogyi
Sales Development Representative

Author

Richárd Konráth
Atlassian Consultant

Author

József Porohnavec
Atlassian Consultant

Author

Péter Orosz
Software Engineer

Author

Alex Nita
Solution engineer - Atlassian

Author

Dósa Zoltán
Agile Coach

Author

Dr. Gábor Manhertz
Vincotech Hungária Kft. - IT Development Team Leader

Author

Christiaan Joubert
Marketing Specialist

Author

Jack Graves
Founder - Capable

Author

Andrea Nikolics
HR manager

Author

Anna Odrynska
Chief Strategy Officer and Co-owner of Alpha Serve

Author

Phill Fox
Principal Customer Success Advocate at Adaptavist

Author

Faith Nyamande
Senior Product Marketing Manager, Appfire

Author

Dr. Varga Balázs
Ügyvéd

Author

Hannes Obweger
Co Founder and Co-CEO at JXL

Author

Gergely Vásárecki
Atlassian Advisor at Bee Wise

Author

Gergely Fehér
Director, SwS Operations and Delivery

Author

Gergely Nyaka
Foreign Business Manager

Author

Zoltán Nagy
ITIL Master

Author

Bence Kovács
Licencing Associate

Author

Alexandra Terék
Support Engineer

Author

Eszter Ernszt-Galamb
Marketing specialist

Author

Tímea Kalán
Senior Controller

Author

Gábor Kozma
Test Automation Engineer

Author

Szotyi
Head of Security

Author

László Csekő
Software Engineer

Author

Bobek
Team Happiness Manager

Author

Annie
Emotional Support Specialist

Author

Márk Szabó
Head of DevOps

Author

Tibor Gyulay
Organizational developer, Trainer, Coach

Author

Emich Szabolcs
Agile coach and Trainer

Author

Warren Da Costa
Senior Product Manager for ScriptRunner for Jira on-premise

Author

Jaime Capitel
Content Creator

Author

Marta Pastor
Product Owner

Author

Marczisovszky Dániel
Atlassian consultant and application developer

Author

Berentey Zsolt
Founder and Front-end Technologies Director

Author

Katelyne Merza
Marketing Manager

Author

Karina Silvia
UX/UI Specialist

Author

Joshua Brock
Author & Technical Writer

Author

Britta Neugebauer
Marketing Manager

Author

Wojciech Andryszek
Content Specialist

Author

Reece Lander
Tech Lead for ScriptRunner for Jira on-premise

Author

Morgan Folson
Product Manager of Custom Charts

Author

Dylan Lindsay
Senior Product Manager

Author

Dea Spiljaric
Product Marketing Manager

Author

Alexandra Szebellédi
HR specialist

Author

Cécile Sablayrolles
Content Manager

Author

Mara Neumann
Marketing Manager

Author

Klaida Sulko
Product Marketing Specialist

Author

Tea Susnjar
Content Writer

Author

Patrick Cartier
Technical writer for Seibert Media

Author

Federico Baronti
Partner Manager

Author

Preston Dube
Marketing Manager

Author

Kamil Beer

Author

Raj Sehmi
Customer Success Manager

Author

Umer Sohail
Product Marketing

Author

Bálint István Berente
Software Engineer

Author

Dr. Zsuzsa Sebestyén
Licencing Associate

Author

Gergely Szikszai
Software Engineer

Author

András Gede
Support Engineer

Author

Levente Nagy
Software Engineer

Author

Dávid Treszler
Video Production Specialist

Author

István Attila Nagy
Software Engineer

Author

Zsuzsa Gábri
Office Manager and Training Associate

Author

Károly Békési
Atlassian Consultant

Author

István Florencio Ascarza
Customer Success Specialist

Author

Andrea Rákosfalvy
Customer Success Specialist

Author

Anna Csapó
Manual Tester

Author

Imre Madarász
Customer Success Specialist

Author

László Sziács
Head of Consulting

Author

Tamás Kiss
Consulting Team Lead

Author

Dániel Szotyori
Customer Support Team Lead & Product Owner

Author

Róbert Szabó
Consulting Team Lead

Author

Fruzsina Sipka
Marketing & UX Design

Social Share Buttons

How to document Jira projects easily

Megjelent:
Frissítve:
How to document Jira projects easily

Ez a bejegyzés több mint 1 éve frissült utoljára, a tartalom bizonyos elemei elavultak lehetnek.

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

Gyakran ismételt kérdések

No items found.

Szerző

Orosz Ákos
DevOps mérnök

Szerző

Bakos Patrick
Test automation engineer

Szerző

Keserű Gabriella
Atlassian tanácsadó

Szerző

Balhási Zalán
Presales Engineer

Szerző

Thorsten Letschert
Product Marketing Manager at Decadis

Szerző

Gizem Gökçe
Atlassian Apps Manager at OBSS

Szerző

Evita Legzdiņa
Marketing Manager at eazyBI

Szerző

Szentesi Zoltán
agilis tréner

Szerző

Content Marketing Specialist at Xray

Szerző

Jay Prakash
Senior Product Marketing Manager at Upscale

Szerző

Danut Manda

Szerző

Richard Birks
Senior Product Marketing Manager at ScriptRunner

Szerző

Yuri Kudyn
Co-founder of Release Management Apps and Journy.io

Szerző

Adler John David
Atlassian tanácsadó

Szerző

Csomós László
Senior Engineering Manager

Szerző

Mozsik Tibor
Marketingvezető

Szerző

Velizar Borisov
Atlassian Community Leader

Szerző

Julia Skoursky
Refine

Szerző

Kecskés Claudia

Szerző

Kubik Ármin
Backoffice csoportvezető

Szerző

Geiszt Csaba
Szoftverfejlesztő

Szerző

Kecskés D. Amadea
Sales Development Representative

Szerző

Tuboly Endre

Szerző

Pilinger Bogi

Szerző

Hevesi Richárd

Szerző

Nagyné Széles Anna
Atlassian tanácsadó

Szerző

Santana Somogyi Lorena

Szerző

Konráth Richárd
Atlassian tanácsadó

Szerző

Porohnavec József
Atlassian tanácsadó

Szerző

Orosz Péter
szoftverfejlesztő

Szerző

Szerző

Dósa Zoltán

Szerző

Dr. Manhertz Gábor

Szerző

Szerző

Graves

Szerző

Nikolics Andrea

Szerző

Anna Odrynska

Szerző

Pill Fox

Szerző

Faith Nyamande

Szerző

Dr. Varga Balázs

Szerző

Hannes Obweger

Szerző

Vásárecki Gergely

Szerző

Fehér Gergely

Szerző

Nyaka Gergely

Szerző

Nagy Zoltán

Szerző

Kovács Bence

Szerző

Terék Alexandra

Szerző

Ernszt-Galamb Eszter

Szerző

Kalán Tímea

Szerző

Kozma Gábor

Szerző

Szotyi

Szerző

Csekő László

Szerző

Bobek

Szerző

Annie

Szerző

Szabó Márk

Szerző

Gyulay Tibor

Szerző

Szerző

Warren Da Costa

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Szerző

Umer Sohail

Szerző

Berente Bálint István

Szerző

Dr. Sebestyén Zsuzsa

Szerző

Szikszai Gergely

Szerző

Gede András

Szerző

Nagy Levente

Szerző

Treszler Dávid

Szerző

Nagy István Attila

Szerző

Gábri Zsuzsa

Szerző

Békési Károly
Atlassian tanácsadó

Szerző

Ascarza István Florencio

Szerző

Rákosfalvy Andrea

Szerző

Csapó Anna

Szerző

Madarász Imre

Szerző

Sziács László

Szerző

Kiss Tamás

Szerző

Szotyori Dániel

Szerző

Szabó Róbert

Szerző

Sipka Fruzsina

Megosztás