Re: "Structured writing = commodified writing"

Subject: Re: "Structured writing = commodified writing"
From: Keith Hood <bus -dot- write -at- gmail -dot- com>
To: Debra Kahn <kahndebra -at- gmail -dot- com>
Date: Thu, 22 May 2014 15:00:34 -0500

Number of product change notices - ye Gods, does that bring back ugly
memories. I once had a job where I had to create a help system for a new
(big) (complex) software package. At first I was creating pages and fully
fleshing them out at time of creation, so the number of pages visible
started small and grew over time. I added hyperlinks for cross-references
as each page was finished. Every week I had to send my latest draft to the
QA guy. And every week, I got buried under a flood of notices about how my
work was full of bugs - i.e., the hyperlinks didn't work.

At first, sometimes when QA guy tried a link, it would take him to a
placeholder page where there was nothing but a notice that the page meant
to be reached by that link wasn't built yet but would be included in a
future draft. Every one of these "busted" links was reported as a bug. I
would send QA guy emails reminding him that some of the links were meant to
be placeholders - just included so he could see how topics were
interconnected and so I knew where to return later to do more work - and
every week he ignored that and reported every such link as a bug.
According to him, they were "broken" because they didn't take him to the
pages that were named in the verbiage of the hyperlinks.

I started putting in such a placeholder link by just putting in the
verbiage that identified the not-yet-done page the future link was aimed at
- QA guy reported those lines as bugs. They were "design flaws" because
they were in locations where a reader was supposed to expect links but they
weren't working as links.

Finally, I went ahead and created every page in the help that I had mapped
out, and made all links active. I had a lot of placeholder pages, which
each had nothing but a title and a notice that the content was still in
development. The titles matched the wording of the links, and every link
actually went to the right page. And after that, QA guy reported every
placeholder page as a bug because the help was "missing necessary

At the yearly evaluations, after months of working 70-hour weeks, I was
denied a bonus because I had too many bugs reported against my work. QA
guy's bonus, of course, was determined by the number of bugs he reported,
so he got a HUGE bonus. And he was an old buddy of the boss, so there was
nothing I could do about 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 @


"Structured writing = commodified writing": From: Cardimon, Craig
Re: "Structured writing = commodified writing": From: Keith Hood
Re: "Structured writing = commodified writing": From: Debra Kahn

Previous by Author: Re: "Structured writing = commodified writing"
Next by Author: Re: Business analysis study group - Washington DC
Previous by Thread: Re: "Structured writing = commodified writing"
Next by Thread: Re: "Structured writing = commodified writing"

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

Sponsored Ads