[Bioperl-l] on BP documentation

[Brian Osborne]

Mark,

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  
idea).


Brian O.


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  
> noires
> such as this one. I encourage ALL to post these issues and help create
> our list of action items.
> MAJ
> _______________________________________________
> Bioperl-l mailing list
> Bioperl-l at lists.open-bio.org
> http://lists.open-bio.org/mailman/listinfo/bioperl-l