mail at michaelbarton.me.uk
Thu Mar 3 16:46:28 UTC 2011
As another example the RSpec library has a nice way of converting the library
specs into html documentation. The code is then self documenting through its
On Thu, Mar 03, 2011 at 10:17:36AM -0600, Chris Fields wrote:
> 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.
> 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
> _______________________________________________ BioRuby Project
> - http://www.bioruby.org/ BioRuby mailing list BioRuby at lists.open-bio.org
More information about the BioRuby