[BioRuby] tutorial

[Michael Barton]

As another example the RSpec library has a nice way of converting the library
specs into html documentation. The code is then self documenting through its
specification.

E.g. http://bit.ly/fG5uNF

On Thu, Mar 03, 2011 at 10:17:36AM -0600, Chris Fields wrote:
> 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
> 
> 
> _______________________________________________ BioRuby Project
> - http://www.bioruby.org/ BioRuby mailing list BioRuby at lists.open-bio.org
> http://lists.open-bio.org/mailman/listinfo/bioruby