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!
Community moderators have prevented the ability to post new answers.
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'.
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
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
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. :-)
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
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.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
anything you could share re: XML/XSLT? thx
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
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:
<?xml-stylesheet href="jira-434-doc.xsl" type="text/xsl"?>
Open the XML file in your webbrowser (may take long for bigger exports!)
Otherwise use a command line tool to convert the XML by using the XSL to XHTML (ok, many abbreviations here :) )
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
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/.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
Yeah - awesome blog ref!
Hat tip for that link!! Nice.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
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
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
Same problem here, http://www.divingintothedetails.com/site can't be accessible now.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
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
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
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
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
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?
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
I still want to be able to diff configurations, and PDF isn't the easiest format for that.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
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.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
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
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
Community moderators have prevented the ability to post new answers.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.