BL> I found it impossible to understand. If I were you,
BL> I'd aim at a slightly lower IQ level (like 100).

PE> I think it's the nature of the beast. MVS documentation
PE> for MVS users, DOS documentation for DOS users, all in one.

Half the problem is attempting an 'all in one'. That just completely
fogs up the documentation with stuff thats of no relevance to a particular
reader and totally obscures what he is trying to find to use himself.

BL> It is very difficult for an expert who understands
BL> something perfectly, to describe it to someone who
BL> doesn't. You come at it with a different mindset.

Oh bullshit, anyone with half a brain can work out what not gunna
be known to the particular audience the documentation is aimed at.

BL> What seems obvious to you, knowing it all, is totally
BL> obscure to one who sees it for the first time with no depth.

More mindless bullshit, its perfectly obvious
what first time users dont know anything about.

BL> I have the same problem,

Your problem is you cant write for nuts Bob,
particularly technical stuff. Paul's even worse.

BL> being an expert in my own field, and what works for
BL> me is to say everything twice using different words.

Thats complete crap too. Half the problem with lousy technical
documentation in a particular area like the one being discussed
is that it often doesnt even present a clear overview of whats
actually being attempted, what the basic purpose of the exercise is.

Then the lousy stuff just starts to use unique terms
without even bothering to clearly explain what they mean.

Any halfway decent technical writer can do it properly, whether
or not he thoroughly understands whats being documented.

And if he doesnt thoroughly understand whats being documented,
particularly the exceptions, he wont be able to document it properly.

BL> It's not even important that what you write is 100% correct.

Thats complete crap too. The LAST thing you want is errors, that just
takes away any confidence the reader might have in the documentation.
They are already unsure that they have understood whats been said with
other than the best documentation, the LAST thing you want to do is add
to that a level of doubt that when they think they do understand what
was being said, that its just plain wrong anyway.

BL> What you have to do is give the reader enough
BL> information to let him make some sort of sense of it.

Yes, you need to do that, AND get it right TOO. Otherwise you
end with a half useful piece of shit that people cant rely on.

BL> The absolute *worst* thing you can do is make a short, blank statement.

Depends on the circumstances. If you say that a VCR will lose whats
been programmed on a power failure for more than 3 minutes, thats fine.

BL> Just think how much trouble "God is Love" has caused over the years.

That aint 'documentation' thats an entirely separate issue.

BL> If god had said it twice using different words, it
BL> would now be perfectly clear that what he mean was
BL> "sex is great" and the Pope would be out of business.

Poor silly senile old Bob.
@EOT:

---