[Interest] query about QT textbooks
Atlant Schmidt
aschmidt at dekaresearch.com
Thu Apr 12 13:39:26 CEST 2012
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.
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.
This is why you'll *NEVER* see good documentation
emerging from a FOSS project. 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. 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.**
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.
Atlant
* As evidenced by the now-infamous "You're doing it wrong"
discussion threads. See especially the comments:
http://labs.qt.nokia.com/2010/06/17/youre-doing-it-wrong/
** Try to write a Linux device driver using the 3rd
(and latest) edition of the O'Reilly book "Linux
Device Drivers" by Jonathan Corbett and you'll
quickly both realize what I mean and be poring
through tons of Linux sources.
-----Original Message-----
From: interest-bounces+aschmidt=dekaresearch.com at qt-project.org [mailto:interest-bounces+aschmidt=dekaresearch.com at qt-project.org] On Behalf Of André Somers
Sent: Thursday, April 12, 2012 05:38
To: interest at qt-project.org
Subject: Re: [Interest] query about QT textbooks
Op 11-4-2012 13:55, Mark Griffith schreef:
>
> I'm not totally computer-illiterate - I have reasonable maths skills
> as an ex-economist, and have built several websites unaided in
> straight HTML without using an editing package or code editor. I have
> written simple programs. But I do have a life outside this world, and
> would like to see software documentation conform to the same standards
> of clarity we expect from (say) people who write company annual
> reports to shareholders - which is about the same level of inherent
> complexity that needs to be cleaned up.
You're an economist telling us that annual reports are easy and clear to
read. Well, me, as a non-economist, tend to disagree. I usually have no
idea what all these economic terms are, and just reading an annual
report does not give me a clear picture of the real position of a
company at all. I just lack the knowledge to appreciate all the figures
and understand them in their relations.
It is much the same with programming: you need some background knowledge
to understand a domain document like the Qt documentation. In Qt's case,
the background knowledge includes the basics of object oriented
programming. Documents like these become unreadable for the average and
the advanced user, if they time and time again explain every detail for
the beginner. As others already said: there are separate books and
tutorials for those groups, so they can gain the needed domain knowledge
to be able to read the documentation.
André
_______________________________________________
Interest mailing list
Interest at qt-project.org
http://lists.qt-project.org/mailman/listinfo/interest
Click https://www.mailcontrol.com/sr/6nrHWJYB26fTndxI!oX7Uun8LHo!qpr3n!++1+rHqtt2m6utHcssJ3ZoQrVI9fB3ocOHxPMdBpObYw94u+b0NQ== to report this email as spam.
This e-mail and the information, including any attachments, it contains are intended to be a confidential communication only to the person or entity to whom it is addressed and may contain information that is privileged. If the reader of this message is not the intended recipient, you are hereby notified that any dissemination, distribution or copying of this communication is strictly prohibited. If you have received this communication in error, please immediately notify the sender and destroy the original message.
Thank you.
Please consider the environment before printing this email.
More information about the Interest
mailing list