JIRA Best Practice & Workflows To Support Documentation/Education Activities.

[Frank Frank]

Hi JIRA Users...

Was wondering if anyone out there has thoughts on JIRA practices/strategy to help support documentation and education activities...

* It's often difficult to get developers to enter 'useful' / grammatically correct description of how changes will impact end user workflows and UI...

* Forcing review/entry of such information too early in the workflow or at the wrong points can often pester/interfere with development; often Business Analysts may be in a better position to provide some of this information - that could be leveraged for training/documentation purposes...

Does any know of case-studies, plugins, resources, articles etc. that discuess how JIRA can be used to help support (by automating the collection of information) documentation and training teams - which need to be aware of soon to be released changes ?

I'm trying to understand what has been tried before and avoid the pitfalls that others may have already navigated ?

Hope to hear from someone...

Thanks

Frank

PS

Some of my ideas:
* Push collection of such info. to code review time (Developers in right frame of reference ?) - Crucible ?

* Collect some of this information at early plannning/scheduling stages ?

* Leverage non-development resources... trainers to follow-up ? business analysts ?

Any real-world experience - war stories out there ?

[Frank Frank]

We ended up rolling our own integration between the JIRA database JDBC connection - and Confluence.

Our utility produces audit-history info. for issues that have been removed from a given release - or newly-added/snuck-in at tail-end - in order to give our writing/education teams visibility.

Back to front:

BMO<=>DAO<=>SERVICE<=> UI

MySQL=>JDBC=>MyBatis=>ConfluenceSOAP/RPC

=> XStream/XML for audithistory

History meta-data is tracked as XML attachment between builds.

Each night - (utility is integrated into nightly-build) - the Confluence content is regenerated - based on the latest info. from JIRA.

Pre/Post pages - which are NOT regenerated each night - allow users to add information, images, etc. to content being extracted from JIRA.

At end of development cycle - a 'deployment' phase - gathers all the pages including their respective pre/post page amendments - and flatens into a single document for distribution...

We export this doc. to PDF.

* The one main lesson learned is to export all JIRA issues - as Confluence "asset" fragments....These "fragments" are tagged accordingly (sometimes with active/ignore etc.) and assembled into any number of summary pages/views we have...

* Also - Confluence could use better identity control for documents. Within a given "space" title is the only thing that drives uniqueness of documents. So - for example - two documents with different parents MUST have different titles - even if their parentsIDs are different ? Too bad... it makes lookup of pages easier in some respects though. We work around conflicts by careful naming conventions: Release:Environemt:Component:SubComponent:Asset

We're hoping - the collaboration - that takes place around the pages much earlier in the process now... produces better documentation in the end, with fewer bottle-necks...

Writers/Educators now get a glimpse of scope of change associated with each release - long before the final flattened "good-copy" document is deployed... everyone participates sooner - better visibility, more time to customize documentation and training - prior to release...

Hope that helps someone...

Cheers