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

[Daniel Friedman <daniel -dot- friedman42 -at- gmail -dot- com>]

I can see the benefit of using JIRA or Bugzilla for docs if you have a team
of writers or own many documents on many different products. In these
cases, there are docs related requests coming from different departments
(QA, tech support, product development) to either update a doc based on a
new release or make a correction or addition based on user feedback. You
would mainly want to list what the change is, what the product model
number/version number it affects is, document the scope of the changes you
must do, and assign an owner and a priority. This way you don't lose sight
of these updates even when there are higher priority projects (e.g. getting
the latest thing out the door) when you get the requests.

<!-- 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.) ->

I think that this is where you write FAQs or knowledge base articles that
are outside the main section of the product doc. Document the workaround in
a quick FAQ, and when the issue is fixed in the next release, you update
the FAQ to tell people the version that fixes the issue. In enterprise you
would probably keep the workaround documented because no one ever wants to
update their apps in enterprise :).

On Wed, Dec 17, 2014 at 2:39 PM, Robert Lauriston <robert -at- lauriston -dot- com>
wrote:
>
> JIRA's for managing and tracking collaboration within a team. I don't
> see that a documentation project would have value unless you had a
> number of writers collaborating on something complex without major
> involvement of engineers.
>
> I create Documentation components in the projects that need
> documentation. Mostly I create issues for that component when I need
> an SME to provide me with information on a closed issue, or on
> something that has no JIRA issue. If I were managing other writers I'd
> probably use that component a lot more.
>
> I generally do not use JIRA as a personal to-do list, I do that with
> flags in the source. For a big release for which it's hard to keep
> track of everything that needs to be documented, I add a
> "doc<version>" label.
>
> When an issue for some other component needs documentation, I put a
> watch on it so I get email to track its status. If it's particularly
> complex, I sometimes create a separate Documentation issue and link it
> "blocked by" the related engineering issue(s).
>
> I would like some custom fields to mark which issues are in which
> release notes. I forget why I didn't set that up.
>
> On Wed, Dec 17, 2014 at 10: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.
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 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 daniel -dot- friedman42 -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
>


-- 
*Daniel Friedman*
*friedmantechpublications.com* <http://friedmantechpublications.com>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 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
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