[Interest] query about QT textbooks

[Atlant Schmidt]

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.