RE: When to write in less-than-perfect Agile

Subject: RE: When to write in less-than-perfect Agile
From: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
To: Robert Lauriston <robert -at- lauriston -dot- com>, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 2 Apr 2014 11:21:37 -0400

Bingo on both.

Janet's notion of a Wiki page might be useful to flag the customer-facing implications of features and changes as they develop. But that requires that I've gotten enough doc'ing done at some particular time.

Currently, I just keep a link available to our daily docs builds, in general, and in the Jira issues that seem to have docs implications, I insert a specific link to affected pages in the docs. But making PLM a watcher on every such Jira issue tends to swamp their inbox (since every change to an affected issue - not just my one or two comments - sends an alert to every watcher).

I find that, early on, the only actual documentation issues that get assigned to me are created by me. I might learn generalities about how the development of some new feature or command-set or API addendum is likely to affect existing product (and therefore docs). Or I get some juicy speculation about the direction some dev is starting to take. But that's usually small potatoes in the greater scheme. The developers don't create documentation clones of their issues (or assign a completed dev issue to the writer) until they've gotten their portions coded and working and peer-reviewed and relatively stable and integrated with the work of other devs on the same project. That comes in later sprints, not early ones.

Our developers are pretty good about alerting the writer when things change, or alerting their managers and team leads who alert the writer, but yes, implications can go unrecognized and stuff can slip into the cracks. A close relationship with the verification test group is essential. They catch a lot of stuff. Certainly they catch things that don't work correctly, but also they catch things that are affected in ways not imagined by the devs. Some of that is iterative during the development cycles, but there's always stuff that becomes apparent when you've got the full working system in front of you, and not just individual functional components. Automated testing is a wonderful thing, but the sharp and imaginative eye of a good tester, along with the blunderings of an enthusiastic techwriter continue to find the unexpected. Usually late in the game. :-)

-----Original Message-----
From: Robert Lauriston
Sent: April-01-14 12:44 PM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: When to write in less-than-perfect Agile

Practicing just-in-time documentation reduces my workload substantially. I can't count how many times something I was keeping my eye on ended up being dropped or otherwise revised so that no docs were needed.

Flip side, peculative, preemptive documentation of work in progress often leads to errors. A programmer changes something, the writer doesn't find out, the doc is wrong.

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.

Doc-To-Help 2014 v1 now available. SharePoint 2013 support, NetHelp enhancements, and more. Read all about it.

Learn more:


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 @

When to write in less-than-perfect Agile: From: McLauchlan, Kevin
Re: When to write in less-than-perfect Agile: From: Robert Lauriston

Previous by Author: RE: When to write in less-than-perfect Agile
Next by Author: Anyone using Wolfram alpha, etc. for work?
Previous by Thread: Re: When to write in less-than-perfect Agile
Next by Thread: Re: When to write in less-than-perfect Agile

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

Sponsored Ads