[Interest] query about QT textbooks

[R. Reucher]

On Thursday 12 April 2012 13:39:26 Atlant Schmidt wrote:
> All:
> 
>   When the world made the change to mostly Free and
>   Open-Sourced Software (FOSS), one of the things that
>   got discarded was good documentation. Back in The
>   Old Days(tm), when software packages cost thousands
>   of dollars, there was money available to pay for a
>   good staff of tech writers, tech editors, and testers
>   to spend the time necessary to create good documentation.
Someone who says that has never tried working with "overly payed" Japanese API 
specs from these "good old days" :)! OK, scratch that, I was trying to make a 
joke from reality here... but actually, I feel much more comfortable with the 
modern FOSS times since many volunteers give away more or less good 
information for "nothing".

Other than that, you're surely right in saying that it would help many 
projects when people were either contributing (i.e. with documentation) or by 
sponsoring / donating. But there are just too many "users" out there that just 
want to consume...

>   But nowadays, the situation is that:
> 
>     1. A FOSS software project has no money flowing
>        in to pay anyone
> 
>     2. So the package's developers work on what
>        they're interested in which is the code.
> 
>   And *THE DEVELOPERS* already know how the software works
>   so *THEY* don't need documentation (or at least not the
>   sort of documentation that a newbie would need to learn
>   how to use the package well and productively). And for
>   the obscure questions that the package developers will
>   have, the documentation probably would never have answered
>   their questions anyway so they look for their answers in
>   the code.
Well, even if there *is* good documentation, many don't even RTFM... that's 
also an issue which may frustrate a number of developers. But I for one still 
document what I do... and I only care about if users can understand that if 
they are willing to somehow contribute or give *valuable* feedback.

>   This is why you'll *NEVER* see good documentation
>   emerging from a FOSS project.
Sorry, but this is untrue. At least the word "never" is a too hard.

>   Oh, you'll see Q&A pages
>   all over Google as users struggle with the same basic
>   questions over and over again (and get what are often
>   wrong answers over and over again*), but clear, concise,
>   purpose-written documentation is rare.
Yeah, *rare* perhaps.

>   Occasionally, a
>   project is big enough to sustain one or two external
>   authors writing occasional paid works about the project
>   and Mark Summerfield's Qt books are excellent examples
>   of that, but the result tends to be a one-shot or few-shot
>   deal and *NOT* documentation that's truly maintained
>   up-to-date. Pick up any book about Linux and you can
>   see the result: odds are the book documents the software
>   *AS IT WAS* several major revisions ago and so contain
>   content that is now not only incomplete but often,
>   quite inaccurate.**
That's a matter of principle: you can only create a document with an "at the 
time of this writing" attitude. Maintaining it is hard work, and for printed 
books it even means a whole reproduction process. Nearly impossible in this 
short-lived times we have nowaydays.

>   What our new world needs is authors who are as inter-
>   ested in giving their output away for free as software
>   designers seem to be. Think it will happen? I don't.
>   So FOSS documentation will continue to suck.
I don't agree totally, but yes, there are just too few good writers out there 
willing to do this for "nothing"...

Cheers, René
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/interest/attachments/20120412/e17cc56e/attachment.html>