RE: JIRA release notes & other doc features?

Subject: RE: JIRA release notes & other doc features?
From: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
To: Robert Lauriston <robert -at- lauriston -dot- com>, TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 6 Jan 2014 10:26:42 -0500


But my understanding is that acceptability of material harvested from JIRA or any other such tool depends on:

a) your organization's standards for the written material in your release notes - descriptions of issues, descriptions of workarounds for issues that remain open, descriptions of fixes for issues that are resolved in the current release

b) the ability of ALL your field reps, engineers, etc. (anybody who is allowed to touch JIRA issue descriptions, summaries of fixes, etc.) to write proper English that is also politically correct (what Product Line Management would want customers to see). The issue gets exposed, but the language sometimes needs... um... spin. And even if it's not spin, an issue often turns out to be something different from what the original reporter thought s/he was seeing.

If you don't have that up-front perfection, then you must do post-processing every time the JIRA feature is run (gawd help you if it's a nightly event), or you must go through all relevant issues with the PLM (and other interested parties) to rewrite the descriptions in-situ, so that they are exported to Release Notes in acceptable form.

In other words, it's not so much a JIRA issue as it's an artifact of any issue-tracking system that has the option to generate "release notes" from selected issue fields. We tried in MKS before the corporate switch to JIRA, and rather gave up at that time.

With a lot of ESL or ETL people, both in our local development office and around the world in the field support and professional services organizations, we had no hope of getting relevant fields to a consistent, acceptable standard without a lot of examination and re-write by managers and techwriters. We're revisiting our processes now that we use JIRA, to determine the best approach. It'll be a while. Don't wait up.

Currently, we just schedule "bug scrub" meetings near the end of a release cycle, to determine which issues are fixed, which are being fully or partially deferred, which ones were the result of in-project churn (i.e., we caused the problem while doing the dev for this release, and we fixed it in this release, so it's not something that needs reporting - as opposed to something that pre-existed and either we're fixing it or we're deferring, or something that we just discovered/broke and are deferring, so it does need reporting). At that time, we decide on rewrites, or not, of issues that will be published.

-----Original Message-----
From: techwr-l-bounces+kevin -dot- mclauchlan=safenet-inc -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+kevin -dot- mclauchlan=safenet-inc -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Robert Lauriston
Sent: January-01-14 3:21 PM
To: TECHWR-L Writing
Subject: JIRA release notes & other doc features?

Any hands-on reports about the JIRA release notes tool or other doc-oriented features?

The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.

New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.

Learn more:


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 for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @


JIRA release notes & other doc features?: From: Robert Lauriston

Previous by Author: RE: Stupid MS Word 2010 Tricks
Next by Author: RE: JIRA release notes & other doc features?
Previous by Thread: Re: JIRA release notes & other doc features?
Next by Thread: RE: JIRA release notes & other doc features?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads