Documentation reorganisation

[Paul Moore]

On 27/07/07, Ian Clatworthy <ian.clatworthy at internode.on.net> wrote:
> How does the Documentation page now look to others? My goal is to get
> the bundled doc updated to reflect the structure shown under Current
> Documentation so please speak up if you have any feedback!

In my view, it emphasizes "advanced" options at the expense of simple
ones. Some examples:

The "Mini Tutorial" doesn't even mention bzr init. To find that, you
need to go to "User Guide", and "Tutorial" within that. On the way to
that page, you've seen links to pages on shared repositories, storage
formats, etc. You're confused before you get there! (I speak from
experience :-)) This isn't good if you're starting from scratch with
some unversioned projects you want to put into Bazaar.

Similarly, there are pages on bound branches and checkouts, but
nothing on "normal" branches. You could argue that normal branches are
too simple to deserve a page of their own, but the result is that only
the more complex forms show up in the top level contents.

Some concrete suggestions:

1. Revise the "Mini Tutorial" to start with bzr init (either to create
an empty repository, or in an existing unversioned project directory),
rather than bzr branch of a pre-existing project.

2. After "Using Bazaar", have a section "Basics" with links to howto
documents covering things like basic workflow (branch, commit,
pull/push), merging, publishing a repository, getting information
(status, log, annotate).

3. Next, have an "Advanced Topics" section, covering shared
repositories, bound branches and checkouts. Move the workflows section
here.

Also, there are a couple of places where the "Documentation Overview"
page and the user guide seem muddled. I'd like to see a single
tutorial, in the overview, covering the best of the existing "Mini
Tutorial" and the "Tutorial" section in the user guide. Also, the
"Workflows" link should go from the overview - leave it to the user
guide. I'd see the "Using Bazaar" section of the overview page looking
like this:

Using Bazaar:
    Mini Tutorial - the five minute tutorial
    Quick Reference Materials - keep these close by
    Bazaar User Guide - how to use Bazaar in practice
    Command Reference - details on all of the Bazaar commands

Then "Basic Topics" and "Advanced Topics" as mentioned above (although
these might better be sections in the user guide, on reflection).

There's a lot of good information in the documentation, and plenty to
satisfy my liking for details and advanced features. But it's a bit
overwhelming to a newcomer.

I've looked at both Bazaar and Mercurial. They are very similar in
many ways, but for some reason Mercurial *felt* simple, where Bazaar
felt much more complex. Aiming the documentation a little more towards
newcomers and basic usage could change that quite quickly. (Of course,
impressions are subtle - where I said simple/complex, someone else
might have seen trivial/powerful...)

I hope this is useful.
Paul.