[BioRuby] tutorial

Thu Mar 3 17:41:52 UTC 2011

Hi Chris,

Interesting. Thank you for your valuable inputs. :-)

So far, the main problem with us is not technical ones but lack of documentation itself (and man power). I personally believe that if we expose more documents on the web, it will raise chances to attract more people.

1) 99.9% of the cases, people try google first. Installed docs are usually hard to find for users and it is very rare that we can't access to the web.

2) Perhaps I don't perfectly understand what you mean, but having the latest version is probably enough in most cases... and we can also include the dump of entire wiki site at that time in the release package, if it makes sense.

3) If you have inline testing framework, it is not that hard. In our case, if I remember correctly, Pjotr have already implemented an inline testing tool for the BioRuby Tutorial (doctest?), so all we need is to run it against the output of the following script, for example.

------------------------------------------------------------
#!/usr/bin/env ruby

require 'rubygems'
require 'nokogiri'
require 'uri'
require 'open-uri'

wiki = "http://bioruby.open-bio.org/w/index.php?title=Tutorial&action=edit"
html = open(URI.encode(wiki)).read
text = Nokogiri(html).search("textarea").inner_text

puts text
------------------------------------------------------------

4) If HOWTOs are maintained as independent files, it still seems to have the same problem -- developers might forget to update the howto files when they made changes in the codes (and, this is the current situation we have now in BioRuby ;-).

Anyway, thanks again for your comments!

Toshiaki

On 2011/03/04, at 1:17, 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
> 