[RFC] Draft 2 of revised mini-tutorial

[John Gabriele]

On 10/10/07, Matthew Revell <matthew.revell at canonical.com> wrote:
> On 09/10/2007, John Arbash Meinel <john at arbash-meinel.com> wrote:
>
>
> > 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?

I like the footnote. The point you're trying to convey is that there's
no syntax-related reason for using an email address here -- it just
works well here. And the footnote does that.

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

My guess is, the new user coming to bzr looking for a mini/5-minute
tutorial already has a directory full of files. They've likely been
using gzip as their "version control" for a while now, and are finally
feeling the pain and taking the plunge into bzr.

Also, right now they're probably deciding between using bzr or some
other alternative (and reading that alternative's getting-started
tutorial).

---John