Documentation reorganisation

[Ian Clatworthy]

Paul Moore wrote:
> 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:
[snip]
> 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).

Paul,

Thanks for your feedback and suggestions. I think most of them are spot
on, though I remain keen on a Complete Reference, not just a Command
Reference. The User Guide in particular suffers from being a
re-organisation of existing material rather than being a fresh look at
what we need. I did that partially because I wanted to be conservative
and not lose anything in the first pass.

I spent a fair bit of time looking at the whole mini tutorial vs
tutorial issue earlier and thinking about which one should stay stand
alone and which one should go into the User Guide. Had we opted to put
the mini-tutorial in and keep the other one independent, the hole in the
User Guide would be even larger because it would go straight from mini
tutorial (in the Intro section say) to 'Advanced Topics' with nothing on
'Basic Topics' in between. :-( So, as I think we're both saying:

* the mini tutorial needs stuff added (though not necessarily everything
  in the larger one)

* the tutorial probably needs to become a 'Basic Topics' section of the
  User Guide in it's own right.

FWIW, my priority right now is getting a first cut User Reference out
and the structure in place within the source tree, hopefully in time for
0.19. After that, I'd like us to fill in the gaps and refine (a lot) the
User Guide in particular.

> 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.

That's something we certainly need to fix.

I must stress how important I think it is to get multiple perspectives
on this and to hear first hand how well our doc is working or otherwise.
Thanks again for the feedback - it's much appreciated.

Ian C.