[BioRuby] tutorial

[Chris Fields]

All,

We are currently having a discussion related to this re: BioPerl docs and the wiki, in relation to our upcoming bioperl release and future directions.  I think our current conclusions are relevant here.

We moved the tutorial and HOWTOs over to the wiki a few years back, and I have been thinking fairly seriously about moving them back to github after the next release, then having a locked wiki page auto-generated from those (with an editable discussion page for suggestions/edits by the community).  This decision is based on several problems we found over the last few years by moving the docs over to the wiki.  

Note these apply mainly to my experiences via bioperl and are primarily my opinions (though some devs have agreed with me), so this may not apply to the bioruby community or even other bioperl devs:

  1) Simple documentation access: what recourse do users have if they can't access the wiki for some reason (server goes down, local network problems, etc)?  Installed docs are always available.

  2) By placing documentation on the wiki (tutorials, HOWTOs, etc), one effectively 'forks' the documentation from the actual distribution.  It has it's own wikified history separate from the code.  That may be okay initially, but then the tendency is that the wiki documentation becomes the 'official' one and only relates to the in-development version or last release of your project.  A way around that is to create possibly API-specific tutorials for specific releases, but they are still effectively separate from the actual versioned code.  

  3) B/c changes in code occur independently from changes in the documentation and they are stored in completely different media (github VCS vc wiki CMS), implementing some nice defensive coding measures becomes harder, if not impossible.  For instance, we're thinking about implementing inline testing for the tutorials and the HOWTOs.  This is intractable if documentation is on the wiki alone and if maintenance of that documentation occurs independently of the code it is documenting.  Not impossible, just harder to maintain long-term.

  4) Finally, we found the initial idea of wiki-fying the docs is in theory well-intentioned (allows dynamic editing of the docs by everyone), but in reality we have found that documentation placed on the wiki tends to lag behind or drift from changes in the code, simply b/c devs tend to forget about the wiki while developing code on github.  Yes, maybe it's a hassle to maintain docs in the repo, but github has mechanisms to allow anyone to make changes (fork/pull request), and if you can set up a system that converts github docs to wiki or another suitable markup, even better (believe me, POD is pretty minimal, so we have our work cut out for us on the perl end).

Again, this may be completely different in the bioruby ecosystem.  Just wanted to share my similar experience with bioperl.

chris

On Mar 3, 2011, at 8:47 AM, Toshiaki Katayama wrote:

> Pj,
> 
> We just discussed about this on the IRC meeting and people agreed to
> maintain the tutorial on the Wiki rather than in the source code
> because people usually search for docs on the web and we can potentially
> involve more people to improve/update the document. Let's see how it works!
> 
> Toshiaki
> 
> On 2011/02/23, at 19:51, Pjotr Prins wrote:
> 
>> On Wed, Feb 23, 2011 at 06:45:36PM +0900, Toshiaki Katayama wrote:
>>> however, I don't know there is a best way to synchronize it with
>>> 
>>> 	http://bioruby.open-bio.org/wiki/Tutorial
>>> 
>>> because Mediawiki format is also a different one from RD and rdoc... Any ideas?
>> 
>> we should drop the Mediawiki version - despite the nice colours.
>> 
>> Pj.
> 
> 
> _______________________________________________
> BioRuby Project - http://www.bioruby.org/
> BioRuby mailing list
> BioRuby at lists.open-bio.org
> http://lists.open-bio.org/mailman/listinfo/bioruby