[BioRuby] tutorial

[Chris Fields]

Michael,

Not sure about rspec, but with POD there are a few POD to wiki converters that generate markup, so it is feasibly possible to automate conversion and uploads to a wiki with a public API enabled (e.g. mediawiki's api.php).  There are also ways via CPAN to interpolate additional markup within POD to allow for inline tests, etc., might as well take advantage of those tools.

The ruby community should have something similar, though with the HTML conversion you showed it makes me wonder if it's even necessary :)

chris

On Mar 3, 2011, at 10:46 AM, Michael Barton wrote:

> 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