The EMBOSS Documentation Project

[jrvalverde at cnb.uam.es]

Damian Counsell <d.counsell at hgmp.mrc.ac.uk> wrote:
> 

Just my 2¢ worth

> What do users want from our documentation system?  What do we want
> from it?  How are we going to store, implement and distribute it?  Who
> should we hire to build it?  What are the prospects for making this
> work a research project in itself?  Who gets the movie rights?

1) I'd say it to be practical, readable and understandable. Readability
depends on using users' language and point of view. If they don't use it, 
it will be worthless...

2) I'd venture we want users to use, torture and exploit it. This leads
to question 5, research:

5) Make it a research project on HCI in Biosciences. What do users *in
all the various areas of Life Sciences* need to use EMBOSS? You need to
target various "markets": obviously Biologists/Molecular Biologists, which
we _believe_ we already know well, but also Medical Doctors, whose needs
are quite different but solvable with the same tools, Pharmacologists,
Population Geneticists, etc. How can one describe a program like CLUSTAL
so it is clear that it is not only useful in building phylogenies, but
also in spotting preserved/differing regions, population variability,
disease relevance, epidemiology dynamics, etc...? AND make it amenable
to all the various target users?

One may of course write looooooong encyclopedic manuals, but I fear no
one would use them (they'd be frightened). Or thousands of Howtos, but I 
fear no one can cover all possibilities. Or find out new, efficient
LifeSci HCI techniques.

3) That should be the result of the project, it might be a "documentation"
database that may be queried by examples, goals, tasks, targets, whatever.
Or a set of GUIs that embed the knowledge on using the software transparently. 
And should hide complexity so users do not get frightened by its volume, and
that appeals to various kinds of users, maybe with customisable or alternate 
UIs. I'm not aware of any field studies on HCI design in the Biosciences,
and there's a serious need for it. We are assuming that the interfaces that
work in other areas should also do here, but is it so? From my experience
I fear not.

Actually many people complains SRS (despite being powerful) is "difficult",
and that W2H is too complex, but they won't like simple forms either.. So,
what the hell do _they_ want? I'd really like to know. Even when they use the
tools, they rarely know something as basic as whom to acknowledge -or how 
to find out whom- for the tools used in citations. Or even if they should 
cite anything.

Had I to bet, documentation should probably be tightly integrated inside
the software UI itself, so that in addition to results it produces guidelines
on how to understand/interpret them, in addition to program listings it
produces "task identification" protocols, etc... Something quite different
from what we have now, may be akin to "wizards" or a mixture between 
a knowledge base, wizards, software, and whoknowswhat younameit.

4) So it should be someone that knows or wills to learn about a) Life Sciences,
b) Bioinformatics, c) Statistics, d) Human-Computer Interfaces, that wills
to work tightly with users, listen to them and translate what they _do_ or
would _like to do_ into easy, amenable instructions/protocols/interfaces.
Someone has to seat down with many users, interview them, generate
polls, collect statistics, implement _user_ drafts (not his/her/or their
advisor at all), and then devise new polls, collect new data and find which
do actually work in each field and why, and possibly -at the very end- try
their own hands at improving user suggested methods.

To sum it up: I'd suggest to start with a blank sheet of paper, fully from
scratch, forget everything done (except perhaps to collect user satisfaction
statistics to start up), and find out what no one else has before: what do
users really want in order to use correctly the software (i.e. making
_educated_ decisions, understanding analysis results from a critical
point of view, and doing responsible use of tools).

Which answers 6) above: credits would go to users, for they would be the actual
source of information, technical tips, UI designs, suggestions, etc.. and
thus results should revert to them (with due recognition to the catalytic
"medium", who would have to sum up statistics and conclusions in papers). 

> You are also encouraged to write to me with suggestions about
> documentation.  I'm relatively new round here so apologies if this
> message falls outside the scope of either of these lists; pretend you
> didn't see it.
>                                                                                 

Dunno if I made myself clear, just ask for anything you want. 

	Hope this helps.

				j