[Interest] query about QT textbooks
R. Reucher
rene.reucher at batcom-it.net
Thu Apr 12 14:02:25 CEST 2012
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>
More information about the Interest
mailing list