[Bioperl-l] on BP documentation

[Mark A. Jensen]

Thanks Brian; these are really valuable insights and suggestions. Of course, the "todo list" is not "mine", but the community's (otherwise, I would have used Post-its), and I have added your action items to it. 

My thinking about a survey is twofold. Intermittent users may, likely will, have different issues than the usual suspects here on the list, or they will put those issues in a different way--likely with more expression of affect, which I personally think is key. It seems to me that documentation is the public face of this project, and hearing visceral reactions from "the public" will help us (or me) prioritize. The other fold is, this kind of data is better acquired a) actively, rather than passively ("Please respond to this thread") and b) anonymously. Obviously, it can't be active in the sense of spamming, but we could reduce the energy barrier by providing something clickable with a few textboxes to the list. 
cheers MAJ
  ----- Original Message ----- 
  From: Brian Osborne 
  To: Mark A. Jensen 
  Cc: BioPerl List ; Chris Fields 
  Sent: Thursday, August 27, 2009 11:10 AM
  Subject: Re: [Bioperl-l] on BP documentation


  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