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.
We record our release note information on Jira issue records - we've added fields to the issue record specifically for this purpose.
We have also created an import function in our old work management system, to import the notes information into there.
We've done it this way because I persuaded the powers that be on the combined need to
a) keep release note information in Jira from as soon as it was possible to do so,
b) keep using our old reporting system as long as we need to - at least until we know we can report from Jira the way we want.
The fields we have added to Jira issue include:
. Include in Release Notes?
. Release Note Title
. Release Note Description
. Old system reference
Our process includes different team members massaging the release note information in discrete stages, and this is easier in Jira than in our previous system.
- Tech Analyst that we have the right stuff while they are coding
- Tester verifies its accuracy while they are testing
- Support Consultant tweaks it for usability when test is complete
- Tech writer style checks it
. Reporter gives it the once over
. tech writer produces a report
. Sprint team then reviews the whole report and lets tech writer know if they have an issue
Sounds a lot but the visibility of changes and comments in Jira makes it easy to communicate. Also I have found that troublesome issues to write about are sometimes troublesome anyway - so there is spin off help in anticipating problems, sharing knowledge, getting other documentation done.
Cheers, Diana
-----Original Message-----
From: techwr-l-bounces+diana -dot- corrigan=visionsoftware -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+diana -dot- corrigan=visionsoftware -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of McLauchlan, Kevin
Sent: Tuesday, 7 January 2014 4:27 a.m.
To: Robert Lauriston; TECHWR-L Writing
Subject: RE: JIRA release notes & other doc features?
No.
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.
