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.
Can I assume that the extensive tweaking and viewing by multiple parties in your Jira system is enforced by workflow?
By that, I mean, can any steps be skipped or taken out-of-order, or when the process and fields were set up, you also adjusted the workflow to ensure that each issue goes through all those hands in that order?
If that latter is the case, then your way seems superior to ours.
Ours works, because we are mandated to have the big bug-scrub meetings before a release cycle can complete. But because it all happens in roughly a one-week period, with a group of people committed to a few hours of meetings (depending on the scope of the sprint we just had), it can often happen that certain key people are not present (vacation, business travel, illness, conflicting meetings for other reasons). There's also the disadvantage that some people are seeing most of the content for the first time, or for the first time since they reported the issue a year ago, so they are rushed to assimilate it and make decisions/suggestions.
So your way makes sense for a number of reasons.
I will begin pushing string uphill to have something of the sort implemented here.
QUESTION: Do you ever get Jira Issues that must change from "Include in Release Notes = NO" to "Include in Release Notes = YES" ?
If so, how is that handled, late in the game, when several people/roles have already handled and passed the issue onward, before it had specific content meant for Release Notes?
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: 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.
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.
