[BioRuby] tutorial

[Chris Fields]

On Mar 3, 2011, at 1:27 PM, Toshiaki Katayama wrote:

> 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

I think this makes sense, as long as there is a migration path to getting important documentation back into the code repository (convert to rdoc, add tests, etc) to make it somewhat officially canonized.  I say that anything used to generate any useful documentation for users is a great thing (specifically if they lower the barrier to participation), but there is a definite need to imbed it properly within the project otherwise it may be lost or wither on the vine.

chris