[Interest] thanks for extra reading suggestions - sorry to insult technical writers

[Till Oliver Knoll]

Am 12.04.12 14:09, schrieb Mark Griffith:
> .

What's that? A mis-configured email client? Or the point you're trying 
to make here? :)

> ...
> I suggested managers repeat the tests I'd done of my versions on the
> most computer-naive users I could find, a couple of the sales girls (who
> much preferred my user instructions to the final versions) but managers
> wanted all the jargon terms I had taken out put back in.

We can understand the frustration which can build up when you're trying 
to improve things, but are being told to do otherwise.

However: you seem to confuse documentation written for developers vs 
end-user documentation. And even in the end-user camp there the range of 
targeted audience is almost infinite: from the experienced studio 
musician, professional office user to the computer novice trying to 
figure out with his "Outlook for Dummies" book what or where the reply 
button in his email client is (*hint* *hint*!).

 > ...
> I understand computers are complex and software is a wonderful thing,
> but I wonder who is really qualified to say what is the most
> sophisticated, elaborate area of knowledge today? Without wishing to
> pull rank, do you really know so much about finance, accountancy and
> economics as to be sure that this is a radically simpler subject than
> software documentation?

I wouldn't say that *documenting* software is more complex than finance 
or the other topics you've mentioned (I am also not saying the 
contrary), but I can assure you of this: after developing software in 
the financial industry for over 4 years I can tell that software 
development beats it all!


The truth is: the financial industry is dead simple compared to software 
engineering: throw a little bit of primary school math like addition and 
multiplication into the game, and you know how Interest Rate Swaps etc. 
work. Add a little bit of statistics (being able to compute the average 
already helps a lot) and you become an economist, and if you know about 
standard deviation, heck, you're champ!


However, trying to explain the "Divide & Conquer" principle to an 
economist guy already hits the rock hard! Recursion? Blows your mind!

Heck, even the attempt to explain how an email client works ("Reply 
button"!) can become a challenge!

Writing about this in easy words? Absolutely possible! But what's the 
point (. taken from above): you would bore to death any software engineer!

> I think there are lots of complex areas of
> knowledge - for example I cannot imagine that electronics - teaching
> circuit designers how to keep unwanted impedance under control for
> example - is an order of magnitude simpler than software writing.

It is. Even though electric circuits are immenselly complicated 
circuits, they all operate according to the same Boolean Logic which is 
fairly easy to understand for every first year student. Heck, that's 
part of any software engineering study, how a CPU etc. works, how to 
compute voltage.

The rest is beating physics and trying to get the production as 
cost-effective as possible.

Challenging, but not as complex and abstract as software engineering.


> ... You see, I'm quite sure that the managers
> who put the buzzwords back into my user manuals would agree with you -
> if you asked them - that (they think) their experience "showed them"
> that user manuals need to be written by people experienced in
> programming, and I'm sure they say this every time.

Well, here I would actually agree with those managers. But again, you 
seem to confuse User Manuals vs Developer Documentation (such as the Qt 
docs you were referring to).

You've mentioned that keywords such as "binary" were unclear to you. If 
that's the case, you are clearly not the targeted audience of ANY 
programmer's documentation!

However, a *basic* book about computers in general (what is a binary, 
what is a file, what is considered a "source file", how do I cope with 
file operations, what is an operating system etc.) would be a better 
match for you.

Cheers, Oliver