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.
Subject:Re: Code Annotation of the Week From:Robert Lauriston <robert -at- lauriston -dot- com> To:techwr-l -at- lists -dot- techwr-l -dot- com Date:Wed, 11 Nov 2009 10:09:46 -0800
There are times when common sense trumps standard procedure, and "Pish
posh Romana, what could possibly go wrong?" is one of them. Outside of
the context of a game or something else frivolous, that must not ship.
True, neither should the tech writer make a unilateral change. If the
responsible person in engineering and his boss are both clueless, the
next logical step would be to pass the problem on to the documentation
manager or whoever the writer reports to.
If that writer reported to me, letting something like that go out for
review would be a major red mark in their annual performance
evaluation, and potentially a firing offense if they'd made similar
On Wed, Nov 11, 2009 at 9:50 AM, Keith Hood <klhra -at- yahoo -dot- com> wrote:
> I think it would have been worse conduct for the tech writer to unilaterally pass judgment on the "fitness" of somebody's else's code. It would have been truly unprofessional if he had decided on his own to omit or bowdlerize the language. That would have been censorship, not documenting.
> He gave the other people concerned, who were perhaps even more responsible, a chance to handle it separately or decide on a different course of action. His supervisor did not tell him to change the wording or omit mention of it. The tech writer followed his orders and did what was expected of him. If there is anyone to be castigated for using improper language or for unprofessional behavior, it would be the other people, not the tech writer who documented the error message.
> --- On Wed, 11/11/09, Robert Lauriston <robert -at- lauriston -dot- com> wrote:
>> From: Robert Lauriston <robert -at- lauriston -dot- com>
>> Subject: Re: Code Annotation of the Week
>> To: techwr-l -at- lists -dot- techwr-l -dot- com
>> Date: Wednesday, November 11, 2009, 11:59 AM
>> And her own boss thought it was OK?
>> It's unprofessional to parrot something that clearly
>> shouldn't be seen
>> by customers.
>> On Tue, Nov 10, 2009 at 8:33 PM, <quills -at- airmail -dot- net>
>> > It was a proper error message linked to an error code.
>> That the error would
>> > not appear because the machine would have melted into
>> slag first was
>> > irrelevant. She would have gotten into more trouble
>> not documenting the
>> > error message. As it was, she did talk first to the
>> programmer, who didn't
>> > see a problem, and then to his first line supervisor,
>> who like-wise didn't
>> > see a problem.
>> > Damned if you do, damned if you don't.
Are you looking for one documentation tool that does it all? Author,
build, test, and publish your Help files with just one easy-to-use tool.
Try the latest Doc-To-Help 2009 v3 risk-free for 30-days at: http://www.doctohelp.com/
Help and Manual 5: The all-in-one help authoring tool. Full support for
team authoring with multi-user editing - both directly and in combination
with VSS-compatible source control systems. http://www.helpandmanual.com/
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-