Best Practice: How to document the JIRA configuration?

NielsJ
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
January 5, 2012

The configuration of JIRA is quite complex (project settings, schemes, workflows, ...) Currently we document these things manually in Confluence. This takes much time, is error-prone and (so I believe) will never be and stay 100% in sync with the actual configuration.

So my question is how do you document the configuration? Are there best-practices? I am wondering if there is a plugin or so that could generate a PDF with all standard JIRA settings (not talking about plugins).

The JIRA Project deployment plugin (https://plugins.atlassian.com/plugin/details/5115?versionId=11213) seems to offer some kind of that feature for projects, but I need it for all the other complex things, too...

Thanks for answers!

7 answers

1 accepted

Comments for this post are closed

Community moderators have prevented the ability to post new answers.

Post a new question

5 votes
Answer accepted
Betsy Walker
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
January 6, 2012

Thanks for the plugin, Andreyev, from my blog. :-)

I also capitalize on Confluence, and document the whole JIRA configuration as the design of a project is being sorted out. For instance, I have a page for documenting the security (users and roles, security scheme, etc) , the workflow transitions (including any groovy, javascript or other 'custom coding' that the workflow invokes), the automated processing (jelly scripts and their schedules), etc.

Much of this could be gleaned after-the-fact thru a database query, with the query results transformed into Wiki Markup as a Confluence table. I do this to document all the custom fields I've defined, for instance, but mostly I've found it invaluable to build the documentation as I go. It helps the business area and JIRA designer speak a common language, as well as ensure all the moving pieces will fit together and produce the desired end result. Another blog post yet to come!

And the documentation is particularly valuable when someone down the road says they want changes to a project I designed months ago, or they want a new project that is kinda sorta like 'that one' and a bit like 'that other one'.

NielsJ
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
January 7, 2012

Hi BetsyW,

I really like the workflow charts of yours. They contain very much specific information about different sorts of dependencies (notifications, roles, ...) I am wondering if it is much work to maintain these diagrams and JIRA in sync. How do you accomplish that? Do you have defined release cycles for the JIRA configuration or a special person caring for the documentation?

Regards,
Niels

Betsy Walker
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
January 7, 2012

Thanks Niels. No, I don't find it much work at all to maintain workflow chart. They are so invaluable that it is absolutely worth the few minutes it takes to make an update to it. In fact, I'd go so far as to say that making detailed charts like this really helps to ensure that you get the workflow design 'right' the first time, and hence future updates are generally few and far between. :-)

2 votes
NielsJ
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
January 10, 2012

I still refuse to accept I have to document my JIRA manually :-) I've been trying out several approaches for an automated documentation:

1: Selenium-Automation to take Screenshots of all administrative pages and merging them to a PDF (too much dependencies, must be a box with X and Firefox installed)
2: Internal rendering of all administrative actions to generate HTML output to generate PDF afterwards (seems too much work)
3: Transforming an XML-Backup via XSL-T

In fact I am currently working on the last approach. First results look really promising.

Andrei [errno]
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
July 2, 2012

anything you could share re: XML/XSLT? thx

NielsJ
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
July 3, 2012

Hi webwesen,

currently I have an early stage that lists all projects, assigned project roles, used permission schemes and permission scheme definitions. Currently works for JIRA 4.3 and 5.0.

How to use:

  1. Get the XSL code from http://pastebin.com/qpKwVdjw and save it to jira-doc.xsl
  2. Make an XML Backup in your JIRA instance and unpack the XML file
  3. Transform the XML Backup with the XSL
    1. for small instances you could edit the XML file and add the line after the <?xml line:
      &lt;?xml-stylesheet href="jira-434-doc.xsl" type="text/xsl"?&gt;
    2. Open the XML file in your webbrowser (may take long for bigger exports!)

    3. Otherwise use a command line tool to convert the XML by using the XSL to XHTML (ok, many abbreviations here :) )

2 votes
AndreyevM January 6, 2012

Get live configurations, save, restore and merge it would be great, but, unfortunately, I don't see Atlassian going to this way...

One option is keep up to date a diagram like http://www.divingintothedetails.com/jira/documenting-jira-workflows/.

Ellen Feaheny [AppFusions]
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
January 7, 2012

Yeah - awesome blog ref!

Hat tip for that link!! Nice.

1 vote
vdastpak January 21, 2014

Hi Betsy,

Your blog post and the http://www.divingintothedetails.com/site in general are unavailable. Is there any place I can read your original blog about documenting JIRA configurations?

Thanks,

Vahid

HarryH
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
March 5, 2015

Same problem here, http://www.divingintothedetails.com/site can't be accessible now.

1 vote
MattS
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
January 12, 2012

Nice blog posts, Betsy!

Documenting a JIRA configuration is harder work than it should be at the moment. I went out of my way to recommend that the configuration be documented in "Practical JIRA Administration" but didn't give any more details. I like the idea of automating it, but what I'm really interested in is tracking changes to it. The JIRA Auditor plugin helps with that somewhat and I recommend it to most clients now.

What I personally do currently is define a document with sections for the Seven Schemes of JIRA, the purpose of Groups and Roles, and the full list of custom field names, types and defaults (plus contexts and screens to be complete). Careful naming of the schemes and their descriptions is also a necessity for long-term maintenance of JIRA.

~Matt

0 votes
Emre Toptancı _OBSS_
Marketplace Partner
Marketplace Partners provide apps and integrations available on the Atlassian Marketplace that extend the power of Atlassian products.
December 13, 2015

We also designed our own documentation format to use through analysis, design and development. It is focused on documenting the workflow and use nothing but Confluence and Gliffy. Below is an article explaining the document format.

https://dev.obss.com.tr/confluence/display/ATLKB/2015/12/03/How+to+Document+JIRA+Workflows

0 votes
Midori
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
May 27, 2014

This is a very interesting topic. There were approaches already mentioned, but let me suggest another alternative.

Write a Groovy script which connects to the interal JIRA API's, collects all data (projects, permissions, fields, workflows, etc.) and then use the PDF View Plugin to render a PDF document by merging that data with a customizable template.

Why?

  1. Groovy is really productive for quickly writing these kind of prototypes. (And you can effectively reuse your Java skills and rely on proven Java libraries.)
  2. In the scripts you have full access to every information stored in JIRA internally.
  3. In the templates you have full control on what data to include and how to display it. (Graphics like workflow diagrams are possible, too.)
  4. Your development pace can be quite fast, as the plugin has an online Groovy and template editor built-in.

MattS
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
May 27, 2014

I still want to be able to diff configurations, and PDF isn't the easiest format for that.

Midori
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
May 28, 2014

Yeah, I totally agree. (Although please note that the subject of this question is "how to document".)

I actually think that a well-formatted human-readable format (possibly with some graphics) is not suitable for diffing, and formats that are optimal for machine diffing (like the XML mentioned previously) are not necessarily human-readable. Ultimately, if both use cases should be supported, some sort of a hybrid method and specialized tool would be handy, but it adds up complexity.

Emre Toptancı _OBSS_
Marketplace Partner
Marketplace Partners provide apps and integrations available on the Atlassian Marketplace that extend the power of Atlassian products.
December 13, 2015

I've added another answer about how we document our workflows. Please take a look at the link below. We solved the compare problem by using diagrams and tables together. https://dev.obss.com.tr/confluence/display/ATLKB/2015/12/03/How+to+Document+JIRA+Workflows

Comments for this post are closed

Community moderators have prevented the ability to post new answers.

Post a new question

TAGS
AUG Leaders

Atlassian Community Events