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: best practices - JIRA fields for the docs team ?
Subject:Re: best practices - JIRA fields for the docs team ? From:Helen OBoyle <hoboyle -at- gmail -dot- com> To:Monique Semp <monique -dot- semp -at- earthlink -dot- net> Date:Fri, 19 Dec 2014 13:51:36 +1100
Hi Monique,
JIRA + fisheye is cool if you keep XML source in a repository, because you
can use a tab in JIRA to see exactly what changes to your doc files were
checked in as a result of that JIRA.
We also use it to manage and track review workflows between our team and
the product development staff.
We use two types of incidents: task and reference task, because more than
half of the doc work we do involves reference tasks. Had I been around
when this was set up, I would have asked for a third: non-reference doc
task. As you say, there are tasks we do that don't involve editing docs,
and it'd be nice to see how much of our time this consumes vs.
non-reference doc tasks that are listed in the same category.
Because we do a lot of reference documentation on what are basically
frameworks, objects and attributes, when we choose reference task and
create a new JIRA, we fill in those fields. For other organisational
reasons, we could not use existing fields, so we created object and
attribute fields just for the doc team. This has proven to be great for
reporting and for showing in dashboards, because we can group things by
framework, or things within a framework by object, to see where our efforts
have gone.
We don't much track "bugs" vs. "new features" because most of our work is
in "new features". Additionally, bug fixes are often positioned as new
features, as they tend to more often be omissions of special cases than of
things that were implemented that don't work.
Sometimes, but not always, our DOC tasks are included within a main
development task's structure, along with design, coding, test, and the
like, but that's also often not the case (particularly with reference docs
as opposed to user narrative docs... the product teams want to make sure
the user narratives are done, but see the reference docs as something that
exists outside the delivery of the feature).
Kind regards,
On Thu, Dec 18, 2014 at 5:20 AM, Monique Semp <monique -dot- semp -at- earthlink -dot- net>
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
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Read about how Georgia System Operation Corporation improved teamwork,
> communication, and efficiency using Doc-To-Help | http://bit.ly/1pJ4zPa
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as hoboyle -at- gmail -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
>http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> 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/1pJ4zPa
