Re: Hyperref queries

Ulrike Fischer <news2@xxxxxxxxxxx> wrote:

Am Tue, 18 Mar 2008 18:08:01 +0000 schrieb Rowland McDonnell:


It's more up your street. I find the hyperref documentation utterly
bewildering - the information is presented in a way that prevents me
remembering almost anything, which is why I've got to write my own
manual. The only way I'll be able to learn is to figure out each
sentence and then write my own explanation

That's the way to understand texts written by other: By translating them
in ones own words and personal way of thinking.

The effort involved in translating most TeX-related documentation into
something that I can understand is far too much work to be worth doing
at all. I've often written my own rather dodgy LaTeX code to do a job
because it was a lot easier than trying to work out how to use something
I'd downloaded from CTAN - or indeed trying to work out how to use
something I found in the TeXbook...

That implies that the style in which TeX documentation tends to be
written in is too divergent from my style of thinking for it to be
useful.

As for me: I've had lots of people compliment me on my unusually clear
and easy to understand explanations - which implies to me that either
I'm a super special person with super special empathy, or that it's
fairly straightforward to write documentation that's massively more
accessible (i.e., needs very much less internal translation) than the
usual sort that one meets.

[Note: something like 80-94% of everything in crap. Most of what I
write is crap. I'm not claiming to be superman - just better than
average at this job, which isn't hard because `average' in this case is
currently `bloody awful']

What do you reckon? Am I some kind of Nietzscheian[1] Übermensch, or
have I come across an indication that most documentation is crap because
the authors can't be bothered to do it properly?

Here's another one: I've got two HP calculators (bear with me, this is
relevant). One's a 1978ish HP32-E, and the other its a 1988-ish HP32-S.
They have very very similar feature/function sets - except that the '88
model is programmable and runs for years off button cells with an LCD
rather than an LED display and 3hrs running off the NiCds.

The really huge differences are in the keyboard - the 1970s calculator's
keyboard is still a lovely thing to use just like new, and the '88 model
still has a mushy keyboard just like new. And - this is where it gets
relevant - in the documentation.

The 1970s documentation was clearly written by `one bloke per book'.
They are coherent wholes, /very/ easy to follow, and so good that I
learnt some maths off the `32E specific manual' (N.B. I was <16 yrs old
at the time and had suffered from a crap maths teacher).

The 1980s documentation? Well, one can just take into account those
parts of the HP32-S's manual that deal with non-programmable stuff.
That means you can compare like with like - the two calcs are pretty
much identical when it comes to the non-programmable things.

The 32S manual takes over twice as much paper to teach you *less* than
you get in the 32E's manual, and it's harder to follow - the 32E's
manual is more useful, /much/ shorter, quicker to learn from, much more
information dense, and containing more information.

And there's certainly no way of learning any maths from the 32S
manual...

The point here is that modern technical documentation is crap. Not all
tech docs used to be crap; almost all are now. There is a -style of?
-approach to? writing tech docs that seems to have taken over, and it's
crap and that's that.

(another point is that HP used to make stonkingly wonderful kit, and
they're crap these days)

That's what I'm doing
with every documentation -- only that I mostly write my explanation down
in my head or as answers for questions in this group and not in complete
manuals.

That works fine if you've got tiny bits of understanding that need
fitting into an existing matrix. Of course one has to do that with
everything - it's how comprehensiion works.

But that method is no use at all if you need to construct an entire
`thought structure' - which is what I have to do. Well, not `no use at
all', but we're talking about a job that's probably harder than writing
the code in the first place if you ask me.

I think you're talking about a job of work that's several orders of
magnitude less effort than what I'm talking about. And I do know what
an order of magnitude is, which is why I said `several' (okay, probably
not more than 3 or 4 orders, orright[2]?)

Rowland.

[1] That's gotta be wrong, but I bet you know what I mean and I'm sure
I can't be bothered to look up the right way to write it.

[2] Okay, so you don't speak English as your native language. But you
are very bright and multiligual[3], so think `very sloppy English
speaker' (me, in slob mode) and I bet you can figure it out.

[3] Just a guess. More than two lingos seems likely to me. Me?
English monoglot and faintly embarrassed about it.


--
Remove the animal for email address: rowland.mcdonnell@xxxxxxxxxxxxxxx
Sorry - the spam got to me
http://www.mag-uk.org http://www.bmf.co.uk
UK biker? Join MAG and the BMF and stop the Eurocrats banning biking
.

Quantcast