Re: Work around.....

[David John <David -at- BMIS -dot- DEMON -dot- CO -dot- UK>]

I can't actually bring myself to disagree with anything in your last post
re: work-around, but curiously, I find it doesn't address any of the points
I made, and it addresses at least one point I didn't make: I don't remember
writing that we are entitled to use potentially unfamiliar terms without
explaining them first.  You, on the other hand, wish to persuade me that I
must use such terms, even if I suspect they are potentially problematical,
on the grounds that they are widely accepted.  I think you will readily
agree that because an expression is widely accepted, does not mean that we
have to use it.

I repeat my wider point so that other list members can ponder it yet again,
and it's quite simple really: your criterion seems to be too narrow to
cover the considerations we must (and do) make as writers in an effort to
improve what we do.   For example, when I saw, in your latest post:

<Yup. And the value I add is the ability to take a spec and a bunch of
programmer notes and turn it into a manual that programmers can understand.
 Seems to be enough in the grand scale of things.>

my immediate thought was: Nope, it isn't enough, and that isn't ALL we
actually do.  OK, so you can produce 'a manual that programmers can
understand'; but what if at least one language element in that  manual:

- violates some legal or stylistic requirement that the organisation is
striving to observe
- inadvertently presents some negative aspect of the feature or process
described
- poses a momentary comprehension problem for readers whose mother tongue
is not the brand of English spoken in your locality
- puts a rival product in a bad light
- somehow just strikes the wrong tone
etc...

Most of the time you're talking to programmers or other specialists, the
language they use would run the risk of doing one or more of those things
if translated wholesale into published information.

And, do we not take steps to prevent the manual being, er, *badly written*
though it pays lip service to language that is understood by its audience?
 By badly written I mean: no structure, inaccurate or missing information,
poorly indexed.   (See Footnote 1).

Shouldn't we be concerned about slang, jargon, some widely accepted
terminology?  Isn't that why we have style guides (See Footnote 3) and word
lists and editors desks and legal editors and approval processes, and so
on?   Isn't that why we get our scribblings reviewed and approved not just
by developers and model users, but also by their managers and our managers?

BTW, the reasons why some programmers (to cite your particular audience)
may find some documentation unusable are many and varied.  Some are just
lazy, some have 'better' ways of finding out what they need to know, and
some documentation is truly appalling and frustrating to use, for one
reason or another.  However, in my view, documentation would be a lot worse
if writers and the organisations they work for did not (as I think they do
currently - at least the ones I know)  fuss over the wider considerations
I'm talking about.   It's most definitely not just about calling a spade a
spade.

-----------------------------------------------------------------------
Footnote 1
The fact that a manual is poorly written does not mean that it can't be
used.  It often strikes me that one enviable and mysterious gift some
programmers have is the ability to use poor material without having to ask
many questions.  This gift is also shared by some infuriatingly bright
youngsters...  Does that mean we can be satisfied with producing poor
stuff, because the target audience can use it?

Footnote 2
I'm not sure myself about this one, but it occurs to me to ask it anyway:
What if we end up with a programmer's guide that  is understandable *only*
by programmers?  Do we say 'that's OK, because it's intended only for
program,mers'.  Hmmm!

Footnote 3
Have you thrown your style guides out the window yet?  You know, the ones
that say things like:
X nonrecoverable [adj]. Use 'irrecoverable'...
X illegal [adj]. Do not use. Use 'not allowed'...

(Copyright belongs to their respective owners, etc...)

I find I need this kind of advice all the time, to stop me saying in
manuals the very kinds of thing programmers say amongst themselves.

Regards,
David.


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=