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
_______________________________________________
Interest mailing list
Interest@qt-project.org
http://lists.qt-project.org/mailman/listinfo/interest
