TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
