RE: SD Times: Tech Writers Should Be Pigs, Not Chickens

Subject: RE: SD Times: Tech Writers Should Be Pigs, Not Chickens
From: "Lippincott, Richard" <RLippincott -at- as-e -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 9 Sep 2013 15:09:16 +0000

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.

Learn more: http://bit.ly/ZeOZeQ

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as rlippincott -at- as-e -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



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.

Learn more: http://bit.ly/ZeOZeQ

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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


References:
RE: SD Times: Tech Writers Should Be Pigs, Not Chickens: From: Chris Despopoulos
RE: SD Times: Tech Writers Should Be Pigs, Not Chickens: From: Kat Kuvinka
Re: SD Times: Tech Writers Should Be Pigs, Not Chickens: From: Tony Chung
Re: SD Times: Tech Writers Should Be Pigs, Not Chickens: From: Robert Lauriston
RE: SD Times: Tech Writers Should Be Pigs, Not Chickens: From: McLauchlan, Kevin

Previous by Author: RE: Chapters must start on recto page???
Next by Author: Re: SD Times: Tech Writers Should Be Pigs, Not Chickens
Previous by Thread: RE: SD Times: Tech Writers Should Be Pigs, Not Chickens
Next by Thread: RE: SD Times: Tech Writers Should Be Pigs, Not Chickens


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


Sponsored Ads