I've been ranting about documentation for years. It's my unshakeable belief that no-one documents their own work well. In the first place, the skills are different. How many programmers have been on any sort of creative writing class? A tiny minority, and for good reason. In the second, even if the programmer is a good writer in other circumstances, s/h/it's too close to the code. Things that are absolutely obvious to the programmer are obscure to the new user. Even assuming those two hurdles away, in the case of commercial software, there is usually a rush to get it out of the door, meaning that documentation gets skimped. This is even more true now that documentation is written for the internet rather than being produced in glossy manuals.

One of the drawbacks of "free as in beer" software is that customer complaints count for less than they do in businesses. This is not to say that the writers of free software don't care about documentation. But they do have other priorities, such as earning a living, and are entitled to do the tasks that interest them (like adding features) first, even assuming that they are able to.

Never having used Qt or QML, I decided to look at one of them - Qt - to see what it does and whether you were being unreasonable. If anything, you were being generous. I have read the entire documentation for Qt.pm and still have not the slightest clue what it does. Those who find this surprising are invited to read http://search.cpan.org/~awin/Qt-0.03/Qt.pm and point out what I have missed.

Regards,

John Davies

In reply to Re: OT: Stupid User Interfaces by davies
in thread OT: Stupid User Interfaces by afoken

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.