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