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.
I'm also working in a Linux engineering environment where Jira is used. (Maybe there are more of us than we think.) I started out asking developers to put me as a watcher on items that required documentation. That sort of worked, when they remembered, but there were real problems with the workflow. Items were being closed once testing validated them, but more often than not, I was still working on the documentation. It was hard for me to keep track of what was documented and approved and what there was still to do. There was no way for me to track my workflow. Even if items were assigned to me, the workflow categories were a poor fit. I tried using spread sheets, tables, etc. to keep track of what was done and what needed doing, but it was a lot of work to keep that up to date.
Now I have a separate Tech Pubs Jira project, with me as the Administrator. I was able to set my own work flow with meaningful steps. Typically the developer creates a Jira item in my project as part of "checking in" the feature or change to the code. It's nice because the Jiras in the Tech Pubs project tend to be short and to the point. I no longer have to wade through all the developers' comments and discussion to try to figure out what changed. It's also great for tracking documentation items, monitoring my workload, and generate reports for my manager.
-----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 Robert Lauriston
Sent: Friday, July 11, 2014 2:40 PM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Using jira for documentation development workflows
I ask people to add me as a watcher on tasks that they think require documentation. I also skim tasks and add myself to the watch list if I see a doc issue. Then I get email when the change is checked in to the main branch and know I can test and document it.
I sometimes create documentation tasks such as "provide information on <new feature> for docs," set the "fix version" to the upcoming release, and assign them to the appropriate developer. That way they show up on the list of open tasks when we get close to release.
Sometimes these are subtasks of a dev task, more often they're standalone.
Sometimes I add a comment asking the developer to assign the task to me when they're done.
On Fri, Jul 11, 2014 at 1:04 PM, Shawn <shawn -at- cohodata -dot- com> wrote:
> 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> 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:techwr-l-bounces+kevin.mclauchlan=
>> 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
>> 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 - 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
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Read about how Georgia System Operation Corporation improved teamwork,
> communication, and efficiency using Doc-To-Help |
>http://bit.ly/1lRPd2l
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as robert -at- lauriston -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/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
