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@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@stat.math.ethz.ch https://www.stat.math.ethz.ch/mailman/listinfo/bioconductor > -- rossini@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}}