[BioRuby] tutorial

[Toshiaki Katayama]

Pj,

On 2011/03/04, at 3:09, Pjotr Prins wrote:

> Not much to add to Chris. The main problem we have now is docs in
> multiple places, and out of sync. Be good to get a coherent whole.
> 
> Wiki's tend to be more inviting, with a vibrant user community. But,
> for BioRuby the Tutorial has been a wiki for years, with no edits,
> that appears to not to work. Also I find Wiki's in general are rarely
> maintained.

This is not limited to the Wiki. Unfortunately, it is also true that
we could not maintain the text version enough, too.

https://github.com/bioruby/bioruby/commits/master/doc/Tutorial.rd

I agree that we need to avoid having multiple places for documents
as long as possible.


> I agree with Chris docs should really be versioned against the
> versioned classes, methods etc. Ideally we should also show
> dependencies and whether they work for Ruby1.8/1.9, JRuby, Rubinius.

This kind of check sheet should be automatically generated (e.g.
using RVM). The results can be included in the RDoc markup of each
method in the source code during the release management procedure.
Then, it will be available via the API reference (http://bioruby.org/rdoc/)
with versioning (because it is embedded in the code).
If we do that, I can agree that it will be useful resource to have.
However, I don't think RDoc is good for beginners to start with
(actually, web interface of rdoc is not friendly even for expert).

We are not talking about these method specifications or validations,
but thinking about the way to encourage writers of the introductory
documents.

Therefore, as for the new attempt, I proposed an idea to organize
a doc team responsible to

* write new documents
* update the existing docs in sync
* maintain a list of available documents coherently

independent from coders. Finally, the team will choose most convenient
technology to use -- GitHub, Wiki or whatever. But, most important
thing is to start writing the contents (than discussing on those choices).

I'm not sure how it works for now, but let's try. Because of the
weekly IRC meeting, I have a feeling that our community is evolving
very quickly toward a right direction and developing good social
interactions as well.

Toshiaki


> For several reasons I personally prefer generated docs. Maybe we
> should think of generating the docs from Doctest files + RDoc +
> Examples - and (cross)-index them nicely. Generation would help for
> plugins too.
> 
> I know it is more work, and not very grateful, but if someone would
> volunteer it would really pay off in the longer term. Note that
> rubygems.org supports rdoc too - so we can host versioned docs there.
> 
> Pj.