Re: Benchmarking Technical Documentation
While, again, it may be useful to completely understand how a product works,
it is by no means essential.
A good analogy here may be creating a fictional character. You may never mention in the book that a character was beaten up for his lunch money throughout the fourth grade, but knowing that fact can help you make his character consistent.
In the same way, a thorough knowledge of the product can tell you what the user needs to know.
To give a simple example, Darren suggests that a complete manual for an analogue watch would consist of three items:
* Winding the watch to keep it going
* Setting the time
* Affixing the watch to your wrist
From an everyday viewpoint, these items might be sufficient. However, a fuller understanding of the watch might lead to other steps, such as changing the battery or extending the life of the watch (which might include the fact that the watch isn't really waterproof).
Just as when you create a fictional character, knowing more about the product tells you more about what you need to write about.
I respond because I'm creating very technical documents for developing
Internet middleware. The sort of understanding you describe would require me
to be a programmer.
Not necessarily. You can be reasonably skilled at reading code without being able to generate it yourself. To give another analogy, this level of learning is equivalent to being able to read French but not write it.
Since the majority of tech-writers (in my experience) do not read code, even this little knowledge is useful.
While this would be beneficial, there are very few
programmer/writers on the market.
Which is why those who exist command top dollar (or pound, or livre). Clearly, there's a demand for this combination. You can make a living, even a good living, without this knowledge, but those who have it probably average higher salaries and get along better with the developers in their company.
I think we create complete documentation,
despite not necessarily knowing how everything works.
Possibly, but you can't really know how complete the docs are if you don't have more than a superficial knowledge. You'll have to rely on your experts. Given the often-troubled relations between writers and their SMEs - in particular the indifference of many SMEs to the quality of the docs - this position seems a very vulnerable one.
Personally, I prefer not to be in this position if I can possibly avoid it. At the very least, I want to know enough to catch when a SME gives me incorrect, misleading, or incomplete information.
Given that, applying
your model, we've no alternative (we haven't the time or resources to become
programmers and writers), the point, I guess, is moot. DB.
It's a big jump from the fact that we often don't have the time or resources to this assumption that we **never** have the time or resources. The fact that we sometimes settle for less than ideal circumstances or results is no reason to always do so.
--
Bruce Byfield 604.421.7177 bbyfield -at- axionet -dot- com
"I saw you, I met you, I had you, I lost you
Lucky I have no disease
I have a habit of taking things lightly
It keeps me off of my knees."
-The Mollys, "Holding On"
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com
Learn about tools and technologies for user assistance developers at
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.com
---
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.
Follow-Ups:
- Needed: advice on 3d rendering techniques, Bruce Byfield
- RE: Benchmarking Technical Documentation, Steve Hudson
Previous by Author:
Re: New TECHWR-L Poll Question
Next by Author:
Needed: advice on 3d rendering techniques
Previous by Thread:
RE: Benchmarking Technical Documentation
Next by Thread:
Needed: advice on 3d rendering techniques
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads