Re: Do I have to understand the material?
1. Do I have to understand the material I am documenting.
... and if you're writing for an authoritative audience.
I'd say you need to understand the material for any audience. The more you know about the material, the more you can anticipate the audience's needs. Yes, writers are often forced by circumstances they can't control to work in less than ideal conditions, knowing less than they could or should. But that doesn't mean that these conditions should be considered acceptable.
No one should fool with fonts. That's what the style guide and style sheets
are for.
To a large extent, Andrew's priorities are valid. Style guides and style sheets don't just appear.Someone has to develop them, and experiment with them until they're suitable.
Also, while these things are important with a large documentation team, they're much less important for a lone writer, a small team, or anyone doing documentation triage.
Really? Are you going to sell your product only to the competition? They're
the only one's who would be interested in your employers code. Does the user
care if you understand the code? No! The user cares if you understand their
problems and their work methods and can explain to them how this product
will fit into their life. They do NOT want to understand the elegance of the
code, the problems overcome. All they want to do is get back to work.
The point is not to know the code or admire its elegance for its own sake, but to use it to help users better. While I'm far from an expert on programming, I regularly find that fumbling my way through the code helps me to track down all the functions of the software that I'm documenting.
That's especially true while the interface is being developed.By reading the code, I can know that I need to document functions that aren't on the interface yet, or are in obscure places that my fiddling about hasn't uncovered.
Just as importantly, many programmers have a habit of building interfaces that are stripped-down versions of the complete functionality. Sometimes, they do so because they think that most users shouldn't know about a particular function. Other times, they simply don't care much about the GUI.By reading the code, I can advocate a more complete GUI, or, at the very least, document the features that don't appear on the interface.
To do that we don't need to read code, we need to read user's, we need to
understand their jobs.
Why are these things mutually exclusive? If you can read the code, then you can help users more. You can also pry more out of the programmers to that end.
Ignorance is not a benefit in ANY industry.
Ignorance is the norm in EVERY industry.
I think this exchange is the gist of Doc's differences with Andrew on this point. Doc is talking about the normal working conditions, while Andrew is talking about what we should aim for.
I think that writers ought to have to have a healthy regard for both viewpoints. On the one hand, we shouldn't let ideals interfer with the reality of deadlines and other normal working conditions. On the other hand, we shouldn't let realism content us with the often inadequate results that we sometimes have to settle for.
--
Bruce Byfield bbyfield -at- axionet -dot- com 604.421.7177
"To Newgate Gaol they took him, the Ranter's dream was dead,
He had no taste for martyrdom; 'I will recant,' he said,
'I banished sin, but I have erred, it cannot be denied
'That these are sin: greed, tyranny, hypocrisy and pride.'"
- Leon Rosselson, "Abezier Coppe"
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Want to support TECHWR-L? Get shirts, bags, hats, clocks,
and more from the TECHWR-L Store. All proceeds support TECHWR-L. http://www.cafepress.com/cp/store/store.aspx?storeid=techwhirl
Save up to 50% with RoboHelp Deluxe. Get 2 great products for 1 low price!
You'll get RoboHelp Office PLUS RoboDemo, the software demonstration tool
that everyone's been talking about. Check it out and save!
http://www.ehelp.com/techwr-l
---
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.
Previous by Author:
Re: MOSTLY OFF-TOPIC: Communicating with the Academic Community
Next by Author:
Re: MOSTLY OFF-TOPIC: Communicating with the Academic Community
Previous by Thread:
RE: Do I have to understand the material?
Next by Thread:
Re: Do I have to understand the material?
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads