[Bioperl-l] on BP documentation
bosborne11 at verizon.net
Thu Aug 27 11:10:30 EDT 2009
Sorry, I'm a bit late here.
I took a look at the Documentation Project page, it is well-reasoned.
However, I didn't see any list of action items there. You do talk at
the end of about soliciting comments, and you've already done this,
and a user survey. A survey is not necessary, the issues are well
understood already. More to the point, you understand them and just as
in coding, "the one doing the work wins the argument".
Here's what my own list of action items would look like:
- Merge FAQ and Scrapbook
-- FAQ is unused or underused and contains code snippets
-- Too much information or too many sections is as bad as too little
- Write Align/AlignIO HOWTO
-- This is the "missing HOWTO"
- Use Dobfuscator links to reveal method documentation
-- Most notably in SeqIO HOWTO
-- Does Deobfuscator have a bug or two that need to be fixed? I use
it, it seems to work but I've heard a rumor...
- Condense and streamline installation documents
-- Remove outdated
-- Still too many pages and too much text
-- There are incorrectly labelled links taking you to the wrong place
-- Remove any text or page that duplicates information in an INSTALL
file, link to this file instead
- Seriously prune the Main Page
-- Wiki's encourage a proliferation of pages and links, the Main Page
is a great example of far too much information
-- Remove many redundant or little used links
-- Try to prettify, in any way possible - we have created, sadly, the
world's ugliest Main Page!
- Revise the SeqIO HOWTO
-- The first HOWTO, and it looks like it
-- Link this HOWTO to the all the Format pages (Category:Formats)
- Feature-Annotation HOWTO
-- Write script that annotates every single SeqIO format, showing
where each bit of text ends up
-- This script runs automatically when you open the HOWTO or click its
link, always up-to-date
-- Probably trickier than I think!
- The "Random Page" exercise
-- Spend some time clicking this link, you will certainly find things
to merge and delete. You will also find nice documentation that you
didn't know existed and is probably never read!
The objective is to create documentation that has a single starting
point for at least 50% of the questions asked in mailing list. We've
achieved this for certain topics, like SearchIO. In the old days you'd
get a query a week about doing something with Blast and we'd repeat
something written the previous week, week after week. Then we wrote
some HOWTOs so the answer to just about any question on Features or
SearchIO was answered by "See the HOWTO".
Again, one starting page for every single reasonably general question,
like "See the Installation page". Not "Starting on the Main Page you
could click on Getting Bioperl or Getting Started or Quick Start or
Installing Bioperl or Installation or Downloads or ...." (you get the
On Aug 15, 2009, at 3:53 PM, Mark A. Jensen wrote:
> ----- Original Message ----- From: "Hilmar Lapp" <hlapp at gmx.net>
>> As for the FASTA example, I can understand - I've heard repeatedly
>> from people that one of the things that they are missing is
>> documentation for every SeqIO format we support (such as GenBank,
>> UniProt, FASTA, etc) about where to find a particular piece of the
>> format in the object model.
> This is the right thread for list lurkers to contribute their betes
> such as this one. I encourage ALL to post these issues and help create
> our list of action items.
> Bioperl-l mailing list
> Bioperl-l at lists.open-bio.org
More information about the Bioperl-l