[MERGE] Bazaar User Guide for 1.0

Matthew Revell matthew.revell at canonical.com
Fri Nov 30 17:46:34 GMT 2007


On 28/11/2007, Ian Clatworthy <ian.clatworthy at internode.on.net> wrote:
> This patch provides a User Guide for 1.0 based on the combination of:
>
> * 6 new chapters (with content stolen from places where it made sense)
> * older content grouped into:
>   - a chapter on Best Practices
>   - a set of appendices.

I really like what you've done. I think it's a clear introduction that
shows Bazaar's power and flexibility and will get developers and
non-developers alike up and running. I think it will hold the interest
of someone familiar with version control whilst explaining enough of
the basics that many non-developer open-source people would find it
useful.

I do have a few suggestions/questions, though, which I'll list below.

1.1.1 What is Bazaar?
---------------------

I like this introductory section because it avoids pigeon-holing
Bazaar as something that's only useful for tracking changes in
software.

I think the text is great for developers but I wonder if a broader
audience may need a little more hand-holding. At this early stage in
the docs, I think we want to capture as many people as reasonable.
Perhaps something along the lines of:

{{{
Bazaar is a tool for helping people collaborate. It tracks the changes
that you and other people make to a group of files - such as software
source code - to give you snapshots of each stage of their evolution.
Using that information, Bazaar can effortlessly merge your work with
other people's.

Tools like Bazaar are called version control systems (VCS) and have
long been popular with software developers. Bazaar's ease of use,
flexibility and simple setup make it ideal not only for software
developers but also for other groups who work together on files and
documents, such as technical writers, web designer and translators.

This guide takes you through installing Bazaar and how to use it,
whether on your own or with a team of other people. If you're already
familiar with version control and want to dive straight in, try our
mini-tutorial `Bazaar in five minutes`_.

.. _Bazaar in five minutes: mini-tutorial/

}}}


1.1.2 A brief history of version control systems
------------------------------------------------

I'd say "Version control tools" rather than "VCS tools", as "VCS"
appears in the numbered list as a product name.


1.1.3   Central vs distributed VCS
-----------------------------------

Typo: "To record or commit these changes, the user needs access to the
central server and they need to unsure", should be "ensure".


1.2.1   A simple user model
---------------------------

I suggest re-writing this section as:

{{{
To use Bazaar you need to understand four core concepts:

 * revision: a snapshot of the files you're working with
 * working tree: the directory containing your version controlled
files and sub-directories
 * branch: an ordered set of revisions that describe the history of a
working tree
 * repository: a store of revisions.

Let's look at each in more detail.
}}}

I think it's useful to go some way in explaining the concepts here and
then explore them in-depth in the dedicated sections.

I know we discussed having the concepts up-front but I'm slightly
concerned that we're introducing a lot of new information to a
non-developer, without any reward (i.e. allowing them to get on and do
something). I'm not proposing we change this now, though.

I also wonder if we should explain "tree" at some point. It's
something that could cause non-developers to stumble because, AFAIK,
it's not in regular use amongst non-devs.


1.2.4   Branch
--------------

"directed acyclic graph" - do we need this up-front? It's pretty scary
:) If so, I think it needs some more explanation. Why is it directed?
Why is it acyclic?


I do have some other suggestions and comments but nothing that I think
needs to happen before the 1.0 release.


-- 
Matthew Revell - talk to me about Launchpad
Join us in #launchpad on irc.freenode.net



More information about the bazaar mailing list