Simplified Tutorial

[Matthew D. Fuller]

On Sat, May 06, 2006 at 08:39:01AM -0500 I heard the voice of
John Arbash Meinel, and lo! it spake thus:
> 
> Well, I used branches with CVS, but I know a lot of people didn't.

Oh, I have too.  But not in most projects.


> I would probably recommend switching your focus from standalone
> branches, into heavy checkouts with a remote repository.

Well, you'll note that the (yet unwritten) third part is intended to
discuss centralized multi-user development, using a pattern like

    (roughly, star-config bound branches, except without the bound
    since 0.7 doesn't have that)

So, if finished out then for 0.8...    8-}


> They can always grow into more.

I'm intentionally fighting very hard to NOT do that; you slip very
quickly from the "use bzr" to "what bzr can do" section, and that's a
"next steps" or "evangelism" piece, not a tutorial.


This perhaps calls for some expansion.  All this is strictly IMAO, of
course.

When I read a tutorial, I feel bound to read the whole thing, front to
back, because there are always side notes and gotchas that can save me
a lot of time.  And also, because I assume that if it's in there,
it'll be there because I need to know it.  If I come out the far side
and can't remember the commands discussed in enough detail to almost
use them in simple cases, it's a failure[0].

When I read[1] the tutorials we have, I start to lose it around where
it goes into branching and merging and other people and so forth.
All that pushes the earlier stuff out of my mental stack, so I finish
the tutorial with some vague notions about parallel lines and merging,
and have to then look back into it again to remember how to create a
branch and add files.  I feel bound to read through it because it's
part of the tutorial (so obviously the author felt I should know it),
and because I just KNOW that if I skip it, there'll be important notes
in there that I'll need to know later, too.

Really, it almost seems like just splitting them into TWO pieces, with
all the branching as a separate piece that I KNOW I don't need to look
at now, would solve the big problem.



[0] Similarly, if it takes me an hour to read through it, it's a
    failure too.  I WANT nice long docs I can pore over at length,
    certainly, but that's after I read the tutorial and decide I want
    to learn more.  We haven't, IME, been all that bad about length
    overall.

[1] Feel free to interpret that as either present or past tense.



-- 
Matthew Fuller     (MF4839)   |  fullermd at over-yonder.net
Systems/Network Administrator |  http://www.over-yonder.net/~fullermd/
           On the Internet, nobody can hear you scream.