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.
RE: Using jira for documentation development workflows
Subject:RE: Using jira for documentation development workflows From:Diane Faris <dfaris -at- sierrawireless -dot- com> To:"McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>, "shawn -at- cohodata -dot- com" <shawn -at- cohodata -dot- com> Date:Mon, 14 Jul 2014 14:40:21 -0700
I suspect the details of the workflow would vary a lot depending on the size and structure of the technical writing group. I'm a lone writer on this project so I opted to keep my workflow pretty simple and to retain control for myself. The stages are:
- To Do
- In Progress (which means I'm working on a first draft)
- Out for review (This includes peer review and SME reviews. I usually leave it at this stage as I do edits and resend for further review / approval, but if it looks like a major over-haul, I'll move it back to "In Progress")
- Done (I originally thought I'd have Done as well as Closed because if there a several Jiras related to the same document, I could declare it Done once that item is approved; but not close it until all the Jiras for the entire document are completed. I find I don't use this much in practice, so if I was setting this up again, I might skip this stage.)
- Closed
No alternate branch paths. I manage all the stages and send doc segments out for review as PDFs using Adobe Acrobat's. I tried attaching the PDFs to the Jira item, but if I did that, reviewers could not add comments. (I'm by no means a Jira expert, so maybe there is a way to do that, but I found it easier to use Acrobat for reviews.) Anyone (developers, product managers, field engineers, tech support, software testing, hardware engineers, etc.) can create a documentation Jira, but I am the only one who moves them through the stages.
-----Original Message-----
From: techwr-l-bounces+dfaris=sierrawireless -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+dfaris=sierrawireless -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of McLauchlan, Kevin
Sent: Sunday, July 13, 2014 11:41 AM
To: shawn -at- cohodata -dot- com
Cc: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: RE: Using jira for documentation development workflows
Well, I hope others can offer useful answers, cuz my answer is âHeck, no!â Weâre not there, yet.
We are feeling our way, here, currently borrowing the workflow used by Dev and Test, in hopes of figuring out a stream that works better for docs.
It might be that the one weâve got would be fine with a tweak or two to the permissions, regarding who is allowed to review and who can promote an issue along its path (or paths).
We are still neatening our Flare projects, prior to putting them into Git for the first time ever. Perhaps after that, the combination of Git and Jira will suggest further adjustments. Donât know yet.
As for Jira flow, for docs (or the stages/flow in other systems, of which Jira is merely an example), I would like to hear
- how many stages people have in their formal doc workflows
- what they are called
- what alternate branch paths are allowed
- who can operate at each stage (for example, do you have a formal stage of peer review, or do you write/correct a portion of a doc and then send directly to Testing/verification who would either resolve/close or reject back )
- as an individual in the workflow, do you have the right to promote or redirect issues/tasks, or does everybody do their part and then send the issue back to a supervisor who decides where it goes next?
Iâm asking these questions of the list in general, not just Shawn.
From: Shawn [mailto:shawn -at- cohodata -dot- com]
Sent: July-11-14 4:05 PM
To: McLauchlan, Kevin
Cc: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Using jira for documentation development workflows
Kevin (et al),
I noticed that you mentioned "Jira" and "documentation" in a single thought. Kind of a rarity, it seems.
I changed the subject so that I am not hijacking the other thread. :)
Being the sole tech writer in a hard-core Linux engineering team, Jira is pretty central to all the development work here. Unfortunately, the current Jira configuration doesn't really meet my documentation workflow requirements. Additionally, I have found very little about this subject on the Web.
Can you/anyone offer advice (or web URLs) on how best to use Jira for technical writing?
Thank you,
Shawn
On Mon, Jun 23, 2014 at 12:00 PM, McLauchlan, Kevin <Kevin -dot- McLauchlan -at- safenet-inc -dot- com<mailto:Kevin -dot- McLauchlan -at- safenet-inc -dot- com>> wrote:
Starting from a history of waterfall-ish development, and after more than two years in-progress, we are in water-agile-fall(**), trying to get to agile, and one outcome of that is that EVERY new thing I add to the docs is supposed to be captured as some kind of Jira issue (story, bug, task...).
So, I never used to ask permission, and now I still don't, directly, but the indirect effect is that that's how it now works.
I have (as we say around here) a whack of issues in my backlog that aren't assigned to any sprint, that aren't supposed to be implemented unless I've got nothing to do. That doesn't happen, of course.
In reality, they'll get snuck into a DOC sprint that we writers are assigning to ourselves, packed among structural and other sanctioned stories and issues. But I thought I'd check which way the winds blow for the rest of y'all*. :-)
(*I'm not southern - I just like to say "y'all" sometimes) (**actually, some product teams, here, are frighteningly agile, while others are still getting onboard - I'm in two that are at different places along that spectrum; if I had rhythm, you could call what I do "dancing"... but no )
-----Original Message-----
From: techwr-l-bounces+kevin -dot- mclauchlan=safenet-inc -dot- com -at- lists -dot- techwr-l -dot- com<mailto:safenet-inc -dot- com -at- lists -dot- techwr-l -dot- com> [mailto:techwr-l-bounces+kevin.mclauchlan<mailto:techwr-l-bounces%2Bkevin.mclauchlan>=safenet-inc -dot- com -at- lists -dot- techwr-l -dot- com<mailto:safenet-inc -dot- com -at- lists -dot- techwr-l -dot- com>] On Behalf Of Mike Starr
Sent: June-20-14 6:39 PM
To: techwr-l -at- lists -dot- techwr-l -dot- com<mailto:techwr-l -at- lists -dot- techwr-l -dot- com>
Subject: Re: What is not mandated is forbidden I never ask permission to put something into a document that can not only help the user but help reduce support queries. If you ask permission, you're just telling them to say no. Had you just put it in there chances are good it wouldn't have been flagged as "out of spec".
Best Regards,
Mike
--
Mike Starr, Writer
Technical Writer - Online Help Developer - WordPress Websites
Graphic Designer - Desktop Publisher - Custom Microsoft Word templates
(262) 694-1028<tel:%28262%29%20694-1028> - mike -at- writestarr -dot- com<mailto:mike -at- writestarr -dot- com> - http://www.writestarr.com
President - Working Writers of Wisconsin http://www.workingwriters.org/
On 6/19/2014 12:14 PM, McLauchlan, Kevin wrote:
> Does everyone subscribe to the notion that customer docs should contain only what is necessary?
--
Shawn Connelly
Technical writer
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.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l
Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l
