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