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

[A.J. Rossini]

Excellent criticisms!  I'm happy that you are willing to answer them
in detail, and look forward to a piece-by-piece description of how we
can improve!  

I'm not joking, and I'm not being snide.  This is a manpower issue,
and having worked with open source projects nearly as long as Eric,
can hardly help but agree with him.  Documentation, for which we do
better than most, is a huge weak spot for this project.

BTW, anyone else who can take a stab at it, feel free to send
criticisms to me, and if relevant or not sure, to the list.  

As a specific task -- we'll be starting API/function/code review
sometime soon, anyone can help with this task, simply build R devel
and try out the new packages, telling us (or me) what you hate.

best, 
-tony 

(speaking in my capacity of Bioconductor release manager, who will be
spending close to a month over the last month and the next two,
preparing the next release which has grown to the point of being
absolutely huge).





"Alex F. Bokov" <yjih74b02 at sneakemail.com> writes:

> 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.
>
> _______________________________________________ Bioconductor mailing list Bioconductor at stat.math.ethz.ch https://www.stat.math.ethz.ch/mailman/listinfo/bioconductor
>

-- 
rossini at u.washington.edu            http://www.analytics.washington.edu/ 
Biomedical and Health Informatics   University of Washington
Biostatistics, SCHARP/HVTN          Fred Hutchinson Cancer Research Center
UW (Tu/Th/F): 206-616-7630 FAX=206-543-3461 | Voicemail is unreliable
FHCRC  (M/W): 206-667-7025 FAX=206-667-4812 | use Email

CONFIDENTIALITY NOTICE: This e-mail message and any attachme...{{dropped}}