[BioC] An ESR essay about software design, and how it applies to Bioconductor

[Alex F. Bokov]

So here goes, I am about to risk getting myself blacklisted by the very 
people I can least afford to be blacklisted by, and at the very start of 
my career no less. Why am I taking this risk? Because I love 
Bioconductor, it's the most useful thing currently installed on my PC, 
and I'm deeply grateful to the developer and user community for making 
such a wonderful tool. The following constructive criticism is how I 
hope to make it better.

Here is an essay by Eric S. Raymond describing the difficulties he had 
configuring a software package on Linux. Obviously the last person you'd 
think of as "computer illiterate", "lazy", or "clueless".

http://www.catb.org/~esr/writings/cups-horror.html

Once you wade through the technical minutia of his specific software 
struggle, the main message appears to be that software is often written 
by individuals who are so knowledgeable in their particular field that 
their idea of "obvious", "self explanatory", "intuitive", "user 
friendly", and even "adequately documented" may be completely different 
from the rest of humanity!  I immediately thought of certain BioC 
packages I've recently bashed my head over (and over and over).

At the end of the essay ESR presents a checklist for telling whether 
your software suffers from problems similar to the ones he describes. 
For the benefit of any package developers/maintainers who may still be 
reading this, here's my version of that checklist as revised 
specifically for Bioconductor:

   1. What does the package look like to a computer person who isn't a
      statistician or a statistician who isn't a computer person? What
      would be the most obvious thing someone unfamiliar with your
      package would try to use it for... and if they did, would they
      succeed after having done nothing more than read the manpage?
   2. Is there any dialogue in the Tcl widgets which is a dead end,
      without giving guidance on what the choices actually do? (although
      if you read ESR's essay you might conclude that there's no point
      to even having widgets, since a GUI does not automatically
      translate into user friendliness)
   3. The requirement that end-users read documentation is NOT a sign of
      failure for a program such as R which mostly lacks a UI... but...
          * Is every argument, method, and slot of every non-private
            object documented in the manpage
            *for that object* (rather than referring to some other
            manpage which in turn refers to another manpage, ad nauseum)?
          * Are the usage examples you give in the manpage simple,
            general, and comprehensible both to statisticians who aren't
            computer people and computer people who aren't
            statisticians? Hint: gratuitous use of functions that aren't
            from the package you're documenting reduces comprehensibility.
          * Does the documentation rely on references to hardcopy
            publications to explain crucial portions of the object's
            functionality instead of using external references as
            supplementary/background material?
          * If there is a significant number of usage scenarios where
            the default argument values will be inappropriate, is the
            user warned?
          * Are the manpages in sync with the current package version?
   4. Do you ever find yourself using any phrase resembling "The syntax
      is just like it is for the S-Plus version"?
   5. Does your project welcome and respond to usability feedback from
      non-expert users?
   6. Do error messages give enough information to be able to
      distinguish between malformed input/arguments, platform
      limitations (memory, drive space, access permissions), problems in
      R itself, and other ("other" presumably being the real bugs)?

Thank you for your patience in reading this. I don't pretend to 
understand the technical complexity of your work, nor your motivations 
for doing it. However, if you do write open source software such as 
Bioconductor packages, it would be logical to at least assume that you 
want other people to use your software. Hopefully the above 
considerations will assist in making that happen.