Re: [ANNOUNCE] Imlib2-Ruby 0.4.0

* Euan Mee ([e-mail]) wrote:
> On 23 Apr 2002, at 1:42, Paul Duncan wrote:
> > * Phlip ([e-mail]) 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.

Imlib2 1.0.5 or newer (it should link against 1.0.4 as well).  There is
a new release of Imlib2 scheduled sometime in the not-so-distant future,
and I will probably add a few defines (specifically, remove the
workaround for the brokem imlib_image_draw_pixel() call and remove the
warnings about buggy clipping in Imlib2::Image#fill_ellipse(), since
both of those bugs have been fixed).

As an aside, a README file isn't just "technical installation
documentation."  It's meant for a number of other things, including a
brief overview of the package's features, the author's information, and
a reference to the license and warranty information.  Regardless, if
someone is looking for a package's library requirements, then the
installation documentation is certainly an appropriate place to direct
them.

> 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'.

It's disingenuous to draw a correllation between shrink-wrapped software
with a price tag and free software with no price tag and a developer who
makes every effort to respond to questions in a timely manner.  I'm not
selling anything, nor am I trying to.  I'm merely providing a tool which
assists Ruby developers, at no obligation on their part.  In this
particular instance, the "customer" has already purchased the product and
has either missed the answer or simply neglected to read the
documentation included with the product.

I don't think it's inappropriate to direct a user (one who has the
software correctly installed) to an answer available in the
documentation, especially when the user in question has made it
abundantly clear that they have already read portions of said
documentation.

> 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>

I realize your rant isn't directed at me personally or my Imlib2
bindings, but I should mention that I did spend a fair amount of time
documenting _every single_ call in the Imlib2 bindings.  The RDoc
generated documentation (available both in the tarball and online at
http://www.pablotron.org/software/imlib2-ruby/doc/) does have a few
quirks (specifically, the prototypes for polymorphic functions are not
correctly extracted from the source.  I have discussed this with the
RDoc author and suggested a feature to correct this behavior), but I
think I compensate more than adequately for those quirks by providing
descriptions and one or more examples for _every single_ method in
Imlib2-Ruby.  I also provide several well-commented example scripts, two
of which are available on the Imlib2-Ruby page, along with their
associated input and output images.  I think it's safe to say there is
more API documentation available for Imlib2-Ruby than for Imlib2 and
Imlib2::Perl _combined_.  

I'm sure you're aware that none of this documentation comes for free.
In fact, I have spent several days time (cumulative) sifting through
the Imlib2 source code, discussing issues with various Imlib2
developers on IRC, and double-checking my Imlib2-Ruby implementation and
documentation with other developers.  In the process, by the way, I 
discovered a bug in RDoc's C parser, and reminded Imlib2 developers about
two existing bugs.  There are at least two developers with a significant
amount of code in Imlib2 who read this mailing list, and I know one of
them can personally vouch for the amount of time I've spent working on
presenting the Imlib2 API in a more palatable form for high-level
developers.

I agree with your sentiment regarding lackluster documentation and curt
or unresponsive developers.  In this instance, however, your implicit
accusation is meritless, misdirected, and in fact an indication of a
lack of research on your part.

> 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
> [e-mail]
> 
> 'I would live all my life in nonchalance and insouciance,
> Were it not for making a living, which is rather a nouciance'
>  - Ogden Nash

-- 
Paul Duncan <[e-mail]>        pabs in #gah (OPN IRC)
http://www.pablotron.org/               OpenPGP Key ID: 0x82C29562