[RFC] Draft 2 of revised mini-tutorial

Matthew Revell matthew.revell at canonical.com
Wed Oct 10 17:56:56 BST 2007


On 09/10/2007, John Arbash Meinel <john at arbash-meinel.com> wrote:

> Maybe "For the rest of this guide". Otherwise it seems a little odd to
> say "we will assume you have it" and then describe (minimally) how to
> install it.

> Or maybe just say:
>
> This guide does not cover how to install Bazaar. It is usually very easy
> to do so, and is described in ...

Thanks, I've used something similar.

> I'm guessing in a 5-min tutorial we don't want to mention that you don't
> have to use an email address. But maybe if we had a link to more
> information? Or we could put it as a footnote. Something like:
>
> your name and email address. [1]_

> .. [1] An email address is not strictly required. But it is the standard
> way of keeping track of people who would otherwise have the same name.
> It also means people who see your great work have a way to get in touch
> with you to thank you and send you money.

I'm worried that such a footnote could overcomplicate what is meant to
be a very simple introduction to bzr. Am I being overly cautious?


> > +Putting existing files under version control
> >  ============================================
>
>
> This section was originally intended for people who already have a
> project they want to start versioning. So creating the files is a little
> bit odd.

I think that title is now wrong but I still think that asking the
reader to create some dummy files simplifies tutorial, because there's
less that can go wrong, and it ensures working with their test branch
will be quick.

> Maybe we can start with:
>
> Often you will already have a project with files that you want to start
> versioning. Assuming you have a project with files like::
>
>   my-project/
>     test1.txt
>     test2.txt
>     test3.txt
>     subdirectory/test4.txt

I worry that the more we leave unspecified, in terms of what the
reader should do and the data they're working with, the less useful
this quick intro becomes. If we spell it out step by step we're
limiting the decisions they have to make and so making it easier for
them to get on with experiencing Bazaar.


> > + $ added subdirectory
> > + $ added test1.txt
> > + $ added test2.txt
> > + $ added test3.txt
> > + $ added subdirectory/test4.txt
> > +
>
> ^- Generally you are showing the command line, and its output. Output
> lines do not start with "$". It might be clearer as

Fixed, sorry, silly mistake.

>

> ^- In your commit messages, you are being a little inconsistent with
> capitalization. "Initial import" versus "added first line of text".
>
> While I'm sure users will always do that, it looks better in a tutorial
> if we are consistent.

Sorry, an oversight.


> > +
> > +  $ bzr push sftp://me@myserver.com/public_html/myproject/
> > +  2 revision(s) pushed.
>
> ^- With 'sftp' you almost always would have this as "/~/public_html/"
> since that is the users directory.
>
> At least *I* haven't seen http repositories which put public_html in '/'
> and then have all files served from there.

Good point. I've changed the main mini-tutorial to feature pushing a
branch to Bazaar, with a link out to using a version that shows how to
use sftp to push to another server.

>

> > +Bazaar won't automatically commit changes from a merge. Although Bazaar
> > +excels at handling complex merges, from time to time you may need to
> > +resolve conflicts or make other minor changes before committing.
> > +
>
> ^- There are more ideological reasons for not doing so. But certainly
> this isn't the place for a long discussion. Even so, this doesn't
> *quite* sit right to me.

How do other people feel about this? Is there a short explanation we
can give that's closer to the full reason? We can remove the
explanation altogether but it might appear that there's an unnecessary
step if we don't explain it.


> > +Learning more
> >  =============
> >
> > -To learn about bzr topics::
> > +To learn about Bazaar::
> >
> >    $ bzr help
> >
> > -To learn about bzr commands::
> > +To learn about Bazaar commands::
> >
> >    $ bzr help commands
>
> ^- I think you definitely want to include some sort of link here to more
> documentation. Maybe some sort of "in-depth" chapter. Or direct links to
> an index/specific workflow discussions/etc.

Thanks for all your input. I'll post the revised version shortly.

-- 
Matthew Revell
launchpad.net

mrevell in #launchpad on Freenode



More information about the bazaar mailing list