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.
>Well I have been given the job of documenting a database product developed
>by a marketing guy. It is horrible. The developer has no idea what tables
>and queries are connected to what forms. He built the program as he went
>along, did not take notes or put in comments. He has forgotten why buttons
>and fields are on a form, but is afraid to take it out. The same form is
>called one thing in one place and another name somewhere else. There are
>hidden fields lying outside of forms and I have to pick through the visual
>basic code to figure out why they are there--the developer can't remember.
This sounds like an example of what I call "Byzantine
complexity": something that is complicated, not because it's
based on difficult concepts, but because it's poorly organized.
Since the software is poorly organized, all you can do is take
extra time to make the documentation as well-organized as
possible. Besides taking time on the actual ordering of
information, plan on lots of headings, and a very incomplete
index. Consider multiple TOCs, too, with additional ones for
fields, table and graphic captions, or whatever else seems
necessary. Users may not be able to learn any general pattern to
the software, but at least they will be able to look up what they
need.
Finally, you should make very clear to the Powers That Be at the
company that this documentation is going to take longer, and why.
Probably, you're not in the position to refuse the job, as one
poster suggested (although the temptation might be
overwhelming!), but, by explaining the problems, you might be
able to avoid a repeat.
--
Bruce Byfield, Outlaw Communications
"The Open Road" column, Maximum Linux
3015 Aries Place, Burnaby, BC V3J 7E8, Canada
bbyfield -at- axionet -dot- com 604.421.7189
"I'll never get to heaven, no matter what I do,
I'll never be a blue-eyed boy, although my eyes are blue,
And I will not work, and I will not work, and I wll not work for
you."
-Ian Telfer, "The Generals Are Born Again"
