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.
I suspect that, as usual, both POV's are extreme and that the Truth lies
somewhere betwixt and between. Any effort to repair substandard
documentation must be viewed in terms of time, effort, and return.
Ultimately, this is not a now/never, either/or question, but one of degree.
In other words, how much Bang do you get for the Buck?
To use the example of adding 2 pts leading...IF it can be accomplished
quickly and easily, w/o impacting the schedule to any serious degree, and
can provide increased retrievability, go for it. If it will take days to
accomplish, the ROI might not be worth it.
But let's take a more substantive example: info mapping. If the existing
text is a blob of undifferentiated text, info mapping might provide greatly
improved retrievability, improved reader comprehension, and (possibly)
result in fewer calls to Customer Support. In which case, the question then
probably becomes one of whether there is room in the schedule to accomplish
info mapping (and the associated question of whether the extra time comes
from nudging out the schedule for the TW or from the TW burning some
And if the TW will be with the project through a number of releases, the
issues become even more muddy. If release X can support only minor
improvement X, perhaps release Y will provide time to implement improvementt
Y, and release Z provides room to implement improvement Z.
OTOH, the rules for a contract TW might be completely different. Or might
not. Depends on the relationship between the contractor and the company.
From: Andrew Plato <intrepid_es -at- yahoo -dot- com>
>--- "Hedley Finger (EPA)" <Hedley -dot- Finger -at- ericsson -dot- com -dot- au> wrote:
>> So, when your client's style guide violates every principle of
>> design and human psychology, it is your DUTY as a professional to point
>> But you cannot simply high-handedly go ahead and implement change. Point
>> out that the client's document comes a poor last to that of the
>> Demonstrate the inadequacy or lack of informative running heads, Make a
business case: my
>> recommendations save $$$$/year in time not lost in trying to locate
>> information. My recommendations will save $$$$/year because FrameMaker
>> conditional docs enable many different product versions to be documented
>> a single file set. Point out the drabness of the cover and layout
>> to the gorgeousness of the Web site and the GUI. Show that restructuring
>> the document will improve maintainability and reader accessibility.
>> that adding 2 points of leading actually improves readability.
>There are times when you have to accept the
>environment as is and make do. Especially as a contractor.
>Many companies don't care about human psychology and the theory of color.
>want docs fast and cheap. They don't need a lecture in the latest
>fad and how the Rational Master Blaster Methodology will make them more
>productive. Sometimes the best solution is to just jam out the docs
>and streamline the process later.
>[P]roduction cycles are
>fast - especially in high tech. There isn't time to waste on showing the
>universe the exquisite wondrousness of leading or single-sourcing.
>Once again - I know it FEELS right to make business cases and show how
>FrameMaker is more valuable, etc. But this is still one-off from what you
>should be doing - writing the damn documents.