[BioRuby] tutorial

[Chris Fields]

On Mar 3, 2011, at 11:41 AM, Toshiaki Katayama wrote:

> 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.

Right, I agree having a nice browsable version present on the wiki or elsewhere is a good idea.  However, does that version need to be the single official one?  Could it be generated, or have a public HTML page linked to?  The RSpec example Michael pointed out could be a very nice alternative.

> 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.

Let's say a user has an older version of bioruby installed.  The official documentation is included with that version.  If that documentation is removed from any future versions, the only thing to point to is what is on the wiki (which may or may not work, but always points to the latest version).  

The tendency then is to suggest upgrading to the latest version that matches the documentation, but that pushes the burden back on the user to upgrade (not always a bad thing, truthfully).  However, if the user is locked in to a bioruby version somehow, they may be suddenly stuck w/o documentation.  

Ex: they are stuck using an old version of ruby due to draconian sysadmins, or they are reliant on a specific piece of code that requires an old bioruby version, and thus can't use the latest shiny bioruby.  Both of these scenarios have been reported by bioperl users in the past.

Regarding including the wiki with the distribution, we had thought about this as well (maybe even including nice PDFs) but it became too much of a maintenance hassle when the PDF generation could be done directly from the wiki itself.

> 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
> ------------------------------------------------------------

Pjotr's mentioned his thoughts on this.

> 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 ;-).

That is a very common community problem, though; bioperl suffers it as well.  The only way around it is to have some sort of workflow that includes tests (including in-line tests) and doc checks prior to commits or releases.  Have a way to implement smoke tests, etc so the community can help on their end.

> Anyway, thanks again for your comments!
> 
> Toshiaki

No problem, glad to give my 2c.

chris

> 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
>> 
>