Question: An ESR essay about software design, and how it applies to Bioconductor
gravatar for A.J. Rossini
13.7 years ago by
A.J. Rossini810
A.J. Rossini810 wrote:
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" <> 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". > > > > 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 > -- 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}}
ADD COMMENTlink written 13.7 years ago by A.J. Rossini810
Please log in to add an answer.


Use of this site constitutes acceptance of our User Agreement and Privacy Policy.
Powered by Biostar version 2.2.0
Traffic: 183 users visited in the last hour