Re: best practices - JIRA fields for the docs team ?

Subject: Re: best practices - JIRA fields for the docs team ?
From: Tony Chung <tonyc -at- tonychung -dot- ca>
To: "shawn -at- cohodata -dot- com" <shawn -at- cohodata -dot- com>
Date: Thu, 12 Feb 2015 10:07:33 -0800

Here's what I'm proposing to my project team, since I have a completely
different set of deliverables timed to align with some but not all phases
of the project:

- a major epic to collect documentation stories for this release
- individual stories related to the deliverables expected for this release

The PM can assign the stories to tie to the specific sprint, so we can
track work progress and burn down.

Can anyone find anything else I'm missing?


On Thursday, February 12, 2015, Shawn <shawn -at- cohodata -dot- com> wrote:

> Hello Monique (et al),
> How did you make out with your quest for information related to jira and
> documentation?
> I am also tasked with creating a suitable workflow in jira. In my jira
> workflow, I need to account for engineering documentation notifications
> (when a change in our project impacts documentation), several QA steps
> (draft QA, QA revisions, and QA final document), etc.
> Any jira workflow examples will be appreciated and in return, I'll be happy
> to share my final workflow (with explanations) to the group.
> Thanks,
> Shawn
> On Wed, Dec 17, 2014 at 10:20 AM, Monique Semp <monique -dot- semp -at- earthlink -dot- net
> <javascript:;>>
> wrote:
> > Hello, TechWR-L-ers,
> >
> > Iâm looking for best practices and advice on how Tech Pubs can best use
> > JIRA. (And this is sort of a long message, but I figure itâs a useful
> > discussion.)
> >
> > I donât think Iâm talking high-level philosophical discussions about
> Agile
> > and working with other teams, but low-level details such as useful
> > fields/values to make it easy to get sensible JIRA reports so that we can
> > easily summarize our âtechnical debtâ, set priorities of individual tasks
> > within a category (such as PDF look-and-feel improvements, which is not
> > easy from DITA source). But perhaps the low-level details must be
> informed
> > by the higher-level philosophy?
> >
> > Background:
> >
> > A while ago I was able to get a DOC project added to our JIRA system.
> > There are separate projects for each main system component, so it seemed
> > appropriate to add a DOC project to the mix.
> >
> > Now I have the opportunity to add whatever fields/values would be good
> for
> > the DOC projectâs tech writers.
> >
> > Thoughts:
> >
> > So, for example, I think that we need more issue types than simply Bug,
> > Epic, Story, Improvement, or Support Incident. It seems that the issue
> > types should be able to differentiate between info for a doc topic vs.
> Pubs
> > tasks such as creating a TXT target in ePublisher or firming up
> screenshot
> > guidelines.
> >
> > But perhaps the usual method is to use the usual Components/s field in
> > JIRA, and to configure the field values for things such as
> Component-1-doc,
> > Tech-Pubs-process, etc.?
> >
> > As well, there is a discussion (which Iâve seen at *every* place Iâve
> > worked in the last few years) about how to treat a software bug for which
> > we need to document how things are now (with the bug), and then when the
> > bug is fixed in a future release weâll need to change the user doc to
> > reflect the change. (Yes, I know that ideally the docs are always âhow
> > things are supposed to beâ and then the Release Notes document the
> > exceptions. But thatâs just not always practical, and certainly not
> helpful
> > to the end user, who months into a release is not expecting to need to
> > refer to the Release Notes.)
> >
> > That is, whatâre the merits of adding a Docs component to the software
> bug
> > vs. creating a child bug in the DOC project? In the former case, there
> > would be no separate JIRA ticket to track for the doc task, which makes
> it
> > harder for the Docs team. But it seems difficult to get software teams to
> > remember to create appropriate separate tickets for the docs tasks.
> >
> > Wrap-up:
> >
> > Of course Iâd like answers to the specific questions Iâve raised, but Iâm
> > sure that there are lots of things I havenât thought of, which is why Iâm
> > looking to the TechWR-L community for a lively conversation :-).
> >
> > Thanks,
> > -Monique
> >
> --
> *Shawn Connelly*
> Technical writer
> <shawn -at- cohodata -dot- com <javascript:;>>
Doc-To-Help: The Quickest Way to Author and Publish Online Help, Policy & Procedure Guides, eBooks, and more using Microsoft Word |


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 @


Re: best practices - JIRA fields for the docs team ?: From: Shawn

Previous by Author: Re: Note versus Tip
Next by Author: Re: "Is it possible for Technical Authors to write content more quickly?"
Previous by Thread: Re: best practices - JIRA fields for the docs team ?
Next by Thread: Re: best practices - JIRA fields for the docs team ?

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

Sponsored Ads