1.0 User Guide progress

Ian Clatworthy ian.clatworthy at internode.on.net
Wed Nov 14 02:58:16 GMT 2007


Ian Clatworthy wrote:

> My personal focus for the rest of this week (4 days) will be publishing
> a (draft) Bazaar 1.0 User Guide. I hope to publish a chapter or two each
> day so people can progressively review it and help where they can.

Here's the progress to date:
http://people.ubuntu.com/~ianc/doc/en/user-guide/index.html.

Points to note:

* chapters 1 and 2 are (largely) new
* chapters 3 to 6 are coming (draft this week is the plan)
* chapters 7 and onwards are mostly older content with headings
  tuned to fit more naturally into the larger document.

I feel pretty strongly that the key to a really good User Guide is
progressive disclosure of complexity, i.e. not going into too much
detail too early. With that in mind, I'm very happy to take stuff out of
the early chapters and put the detail elsewhere if people feel that
doing so would help.

At this point, the main things I'm after feedback on are:

1. Does the overall organisation look OK?
2. Readability and flow of chapters 1 & 2
3. The core concepts section in particular (it was based on
   the recent thread re fundamental abstractions).

If anyone has some time to put together some diagrams to go into
Core concepts, that would help a *lot*. (I find producing diagrams 10x
slower than producing text but they can be so useful.)

Thanks,
Ian C.

PS: Existing topics yet to be incorporated are tutorial.txt and
conflicts.txt. These will be expanded/included into chapters 3-6.



More information about the bazaar mailing list