Re: departing from a template

Subject: Re: departing from a template
From: Bruce Byfield <bbyfield -at- axionet -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 17 Apr 2002 18:35:57 -0300


Martha J Davidson wrote:



If, however, you mean a standard framework or outline that you use
to address the topics you are documenting, then I agree with you.
It's always helpful to start with a basic structure that covers the
main topics you are likely to cover as you document different aspects
of a system, but no structure can accommodate all of the topics
you are likely to need to address.

A good illustration of this point: a very large company (that will remain anonymous) spent a good chunk of money buying such a framework from a consultant firm. I've gone through much of the resulting documentation, and the quality ranges from poor to completely inadequate. So far as I can infer, people felt that, so long as they had put something under each heading, then they had done their job. Their managers signed off in the same spirit, and the resulting documents were carefully stored on the servers,where they occupy gigabytes of space, are never used, and are becoming obsolete. Just as before the great documentation effort, anyone who needs concrete information in the company sidles over to the handful of knowledgable people in the company, or sift through old e-mails and folders of saved snippets of information. Out of several hundred documents,only three or four - all written by the same person - were complete enough that I could actually use them to go through a process.


I'm not saying that outlining has no purpose. Obviously, it does. However, keeping too closely to such a framework can be as inefficient as plunging into a documentation project with no planning at all. In fact, in some ways, it may be worse. Some people can work quite well without a plan, and, even those who can't at least have a chance of seeing some sort of order as they stumble along. Without a plan, writers may be inefficient, but they might still manage to produce documentation that's useful. However, as in the company mentioned aboved, it's perfectly possible to complete a rigid outline and never notice that the result wasn't worth the effort.

--
Bruce Byfield 604.421.7177 bbyfield -at- axionet -dot- com

"Never eat at a diner called 'Mom's,' never play cards with a guy named 'Doc,' and never get involved with a woman who's got bigger troubles than you."
- Nelson Algren, The Man with the Golden Arm




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com

Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.



References:
Re: departing from a template: From: Martha J Davidson

Previous by Author: Re: Font Selection Methodology
Next by Author: Re: A Simple Philosophy
Previous by Thread: Re: departing from a template
Next by Thread: Re: departing from a template


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


Sponsored Ads