RE: best practices - JIRA fields for the docs team ?

[Rebecca Officer <Rebecca -dot- Officer -at- alliedtelesis -dot- co -dot- nz>]

Hi Monique

We've got a separate Docs project and we've kept it very simple. We've only one issue type, and we use labels to sort issues. Labels are really versatile as filters. Unless you've got a big team, do you really need heaps of issue types? Likewise, our workflow is minimalist: don't-start-yet, to-do, in progress, tech review, peer review, done.

We went for a separate Docs project so we could make the workflow really simple and put fields in that suited us. Before we moved to JIRA, we included Docs tasks in software issues. I find it much easier having separate Docs issues!

We get a separate DOCs issue for each docs-affecting software issue, automatically. Software issues have a field that asks whether they changed the user interface behaviour. If the software engineer says yes, JIRA automatically creates a Docs issue and links it to the software issue. That way you don't have to worry about the engineers remembering to make a Docs issue. This is done through a free JIRA plugin called Groovy Script Runner. 

Our JIRA admin sent me more info about the automatic process, which I've put below. If you want to implement this, that might help your JIRA administrator.  

Cheers
Rebecca


More info from our JIRA administrator:

---------
Hi Rebecca,

We're using cloning behaviour, automated through a plug in.

Background: Jira does allowing cloning of issues, but out of the box it's a manual process with no way to automate it. We've got a free add-on that allows this to become an automated action.

The free plugin is Groovy Script Runner. There's a good chance that it is already installed on their Jira instance, because it is one of the most popular 3rd party add-ons. It is completely free and adds many powerful things that Jira simply can't do out of the box.

When this is installed, a new workflow Post Function is available, which is "Clones an issue and links". It allows for the target project issue / type to be configured, and has configurable groovy conditions and actions to allow further customization.

In our case, the clone is triggered if a software issue says Yes to 'CLI / SNMP / GUI affecting'. It makes a Documentation issue of type 'Docs CR' and copies boilerplate headings into the issue description. 

Our configuration looks like this:
===================================
Condition: cfValues['CLI / SNMP / GUI affecting'].value == 'Yes' && !issueLinkManager.getOutwardLinks(issue.getId())*.destinationObject.projectObject.name.contains('Documentation')

Target Project: Documentation

Target Issue Type: Docs CR

Additional issue actions: issue.description = 'h4. +Text in need of modification:+\n\n\nh4. +Explain why:+\n\n\nh4. +Suggested Text:+\n\n\nh4. +Relevant Output Examples and show commands:+\n\n\nh4. +Relevant Config Example:+'

Issue Link Type: Relates To
===================================

The condition ensures we only clone an issue if the user has indicated they changed the CLI/SNMP/GUI, AND that there is not already a link to a docs CR. This catches two cases: where a user has conscientiously already created a docs issue and linked it, or if an issue goes through a repeated resolve - reject - resolve - reject loop between software and test, we don't want to make a new clone each time because that would be confusing. The condition depends on the target project being called Documentation.

It should be possible with the Additional Issue Actions to customize the resultant cloned issue further - in our case for example docs CRs have a 'creator' of whoever raised the original issue, which is usually a tester, when for us it would be better if it were the developer. I spent some time on this but couldn't get a solution so left it as-is. 



There is also another paid-for add-on called Clone Plus for Jira, which may be required if the Groovy Script Runner doesn't offer enough customization, however we don't have Clone Plus for Jira so I can't really comment on how useful it is.

If they're running Jira Cloud, then these add-ons may not be available, although I think GSR is.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1pJ4zPa

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications?  Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions?  Search our public email archives @ http://techwr-l.com/archives