cjfields at illinois.edu
Thu Mar 3 19:39:56 UTC 2011
On Mar 3, 2011, at 1:27 PM, Toshiaki Katayama wrote:
> 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
> This is not limited to the Wiki. Unfortunately, it is also true that
> we could not maintain the text version enough, too.
> 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
> 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.
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.
More information about the BioRuby