Documents, in bzr or wiki

[Ramon Diaz-Uriarte]

On 5/15/06, Alexander Belchenko <bialix at ukr.net> wrote:
> Erik Bågfors пишет:
> > Just a thought, having the documentation on the wiki has been very
> > good from a "let's get lot's of document done", but it's gotten to the
> > point where lot's is out of date, for old versions, etc.
> >
> > The problem with the wiki is that some document has to say "this is
> > supported in 0.8 and up", "this is how you do it pre 0.8, this is
> > post", etc.  This will only get worse. It's also very adhoc, people
> > write what they think is important.
> >
> > I would like us to create a new manual with a good structure, real
> > thoughts on what should be included, and that should include
> > tutorials.  I really find the darcs manual easy to use.
> > http://www.darcs.net/manual/bigpage.html.  I also think that the
> > documentation should be in the bzr branches, so that we can keep them
> > up to date with the version in the branch and not with all versions
> > out there.

But I think that both Darcs and Monotone (another great piece of
documentation) use a manual that is authored by just one or a few
people. This is very different from a wiki-style work. And would
require individual authors to commit to keeping their docs updated.
Maybe the wiki approach is not incompatible with the "few-authors
manual". In addition, the wiki pages can be authored by anybody, even
those who, like myself, have only been using bzr for a week or so... I
don't think "The" bazaar manual should be put together as a wiki, but
should rather have more quality assurances on what goes there.


> >
> > I think bzr is mature enough to make documentation a very important
> > thing right now.
> >
> > What do people think?
>
> I'm strongly positive for all proposal.
>
> I'm also time to time find this wiki-based site slightly amebiform
> because for me personally it lacks main navigation menu at the top or at
> one of the side (prefer left) of each page with helpful navigation. I'm
> often find myself that to some part of site I can get from other side of
> site only via FrontPage that have sidebar with simple menu,

I definitely agree here. I often need to keep a tab open with the main
bazaar page, because it is the only one that allows me to access other
pages.


or by
> clicking by 3...5 links that generously scatter via all pages. I'd like

I agree too.

> to see more conservative style. Probably something like python.org site,
> something more predictable with tree directory structure instead of
> current plain big set of pages. I's just wishlist. But it probably is
> not compatible with wiki at all.
>
> Something like:
>
> http://bazaar-vcs.org/
>         documentation/
>                 tutorilas/
>                 user manuals/
>                 faqs/
>         downloads/
>         development/
>
> and so on...
>
> --
> Alexander
>
>
>

R.
-- 
Ramon Diaz-Uriarte
Bioinformatics Unit
Spanish National Cancer Centre (CNIO)
http://ligarto.org/rdiaz