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.
There's another aspect to the "committed" view that hasn't been much discussed. We've been talking quite a bit about commitment in terms of contribution to the project and its goals, but we've mostly overlooked the commitment of dealing with aftermath of product failure. With some products, that aftermath can be deadly. When that happens, one of the first things that the investigation teams and lawyers do is start examining our work to see if the accident was caused by poor documentation.
Some of you who know me personally have heard me refer to what I currently document as something that can "kill you in almost every way possible." Deadly high voltage, extremely high energy X-rays, large moving parts, deadly gasses, and oh yeah our service engineers are at risk of a fall from a high place while performing certain tasks. I've more than once been tasked to generate revisions when safety issues were unexpectedly encountered out in the field.
More than once I've sat in meetings where I was told "Just take the operation for this new feature and stick it in an appendix at the back of the book," to which I've objected "Having the users jump around like that is a really good way to get the users accidentally [insert one of several nasty outcomes here], so....no. Instructions for this will be incorporated into the flow of operations as they should be." (Why project managers sometimes think that I'll write faster if the data is in "an appendix" than I'll write if the data is in the main flow of the manual is beyond me, but I digress.)
For many of us, bad documentation means that the worst that can happen is loss of data. For some of us, the worst that can happen is loss of life. Ensuring that this doesn't happen is a commitment.
Yes, I'm a pig.
--Rick Lippincott
-----Original Message-----
From: techwr-l-bounces+rlippincott=as-e -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+rlippincott=as-e -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of McLauchlan, Kevin
Sent: Sunday, September 08, 2013 9:15 PM
To: Robert Lauriston; Tony Chung
Cc: Chris Despopoulos; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: RE: SD Times: Tech Writers Should Be Pigs, Not Chickens
Hear-hear!
Also here-here.
When they come from PLM, they are almost always too broad and fuzzy.
Early-on, I would attempt to entreat, cajole, or browbeat the PLM into revising stories that affected me, to make them useful.
It was like pulling teeth to get him/them to pay enough attention to make it work. "Just document it!"
After a while, I switched tactics. I now give 'em either exactly what they asked for (if that can be determined), or my best guess (with or without the use of a dartboard).
Then I submit the resulting doc for review and wait for the squawks.
Either the PLM sees the result and sends the story/issue back to me with notes and clarifications, or the tester goes after him, seeking usable criteria for judging what I've presented... and the PLM sends the story back to me with notes and clarifications.
Based on the text of the complaint/review-suggestion(s), I re-research, rewrite, and re-submit.
Rinse, and repeat.
This is actually less frustrating than trying to get the stories done to a decent standard, up-front.
Over the long haul, I think the new stories are actually improving. I like to think I'm having some effect there. :-)
-----Original Message-----
From: Robert Lauriston
Sent: September-06-13 4:22 PM
To: Tony Chung
Cc: Chris Despopoulos; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: SD Times: Tech Writers Should Be Pigs, Not Chickens
In a properly written user story, the acceptance criteria define what needs to be documented.
I think ambiguous / incomplete user stories are the #1 way people do agile wrong.
On Fri, Sep 6, 2013 at 10:41 AM, Tony Chung <tonyc -at- tonychung -dot- ca> wrote:
> And I guess depending on the quality of the user stories, it may be
> easier to identify the user's desired tasks so that the writer isn't
> writing only reference material.
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.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
