On 23 Apr 2002, at 1:42, Paul Duncan wrote:
> * Phlip (phlip_cpp / yahoo.com) wrote:
> > Paul Duncan wrote:
> > > I just posted Imlib2-Ruby version 0.4.0, my Ruby bindings for
> > > Imlib2 (http://www.enlightenment.org/pages/imlib2.html).
> > 
> > A> What version of Imlib2 does it bind to?
> 
> I mention that in the README.  

<rant apology="yes" excuse="Sorry, but its touched a raw 
nerve"> 
This is on one of my pet hates. Top-level documentation that 
doesn't give top-level information. In this instance, 'Sales' info - 
info used to get folk interested in using a product - that doesn't 
allow the people who receive it to tell whether the product is of 
interest or not.  Instead, one is left to get the product and read 
the technical installation  documentation to then make the 
check to see if it's of sufficient interest to acquire the product.

But that's not the main point of the rant.  

The main point is that, when someone asks a quite 
reasonable top-level question, they are told that 'the answer is 
inside the product's packaging'.

I'm fed up with this blindness to the needs of the recipients of 
a communication in cases like this where it is wilful, and when 
the outcome of the blindness is then 'complained' about by the 
perpetrator."
</rant>

Well, that's /my/ blood pressure down a bit!

Other instances of this effect are 'Help'/'About' dialogues which 
tell you the name of the product, and the version, but not a 
one-liner on what the product is intended /for/.   Especially, 
but not only, when there is no overview of the product's 
purpose and features in the help files.

A third instance is documentation that is vague, and then 
gives the top-level URL of a breathingly vast web-site, in lieu of 
the specific nugget of information the section of the 
documentation is about.  

I spent half-a-day recently as a result of this approach - this 
was in documentation for a 'firewall appliance'  Linux distro, 
and it said 'to find configuration details go to linuxdocs.org'.

> The version of Imlib2 I have
> installed is 1.0.4, although it should work correctly with future
> releases as well.
>
> > I know you can't answer the last question, but you could
> > obviate it by answering the first with an URL

If anyone is interested in a moment of epiphany allowing a 
smooth and effortless move to user-centric development, I 
strongly recommend a swift read thro' "The Design of 
Everyday Things" by Donald Norman.

Too few software designers, builders and documenters read it, 
IM strongly-held! :-) O.  In fact, too few people read it.

Thank you for your kind tolerance in reaching this far.





Cheers,
     Euan
xlucid / users.sourceforge.net

'I would live all my life in nonchalance and insouciance,
Were it not for making a living, which is rather a nouciance'
 - Ogden Nash