[SvnBook] #98: ch01: major reorganization

[SvnBook]

#98: ch01: major reorganization
-------------------------+--------------------------------------------------
 Reporter:  cmpilato     |       Owner:  nobody
     Type:  enhancement  |      Status:  new   
 Priority:  normal       |   Milestone:        
Component:  content      |     Version:        
 Keywords:               |  
-------------------------+--------------------------------------------------
 I'm dissatisfied with some section ordering and the knowledge dependency
 graph in our book.  Currently on my hit list is Chapter 1.

 The chapter starts off with this weird section that conflates the idea of
 a "server" with a "repository".  The very word "server" evokes thoughts of
 networks, but of course networked operation is not a version control
 basic.

 Anyway, that is followed by the explanation of the various version control
 models, which is the highlight of the chapter for me.

 At this point, we're at the perfect place to talk about working copies.
 Now, neither of the version control models requires a physical working
 copy.  A VC tool could rebuild and manage in memory the same stuff that
 today lives in the .svn directories with each invocation.  But Subversion
 has chosen to use a physical working copy, a cache of some of the most
 commonly accessed bits of repository data.  It is in that
 working "copy" where we do the "modify"cations that we later "merge" into
 the repository.

 But we don't introduce working copies.  We talk about URLs, because they
 help us explain how to ''get'' a working copy.  ''Then'' we talk about
 working copies.  But as part of talking about working copies, we throw up
 a sidebar about URLs again.  It's in this sidebar that we finally get
 around to mentioning that Subversion is a networked version control
 system.

 After that, we bring up revisions.  But why didn't mention revisions way
 back we introduced the idea of a repository that remembers every change
 ever written to it?

 Finally, we talk about mixed-revision working copies, which I suppose is
 fine.

 I'm so confused when I read Chapter 1 that I'm not sure I can even make
 clear suggestions on how to fix it.  But here's a straw man (I'm shooting
 from the hip here, and aiming for clear layering of generic VC concepts
 with Subversion specifics):

  * An introduction to version control (no Subversion info allowed!)
    * The repository (where your version controlled data is housed)
    * Revisions and versions
    * Version control models
  * How Subversion does version control
    * Subversion's high-level architecture (moved from the preface)
    * The Subversion repository (as a collection of tree snapshots,
 addressable by a client using URLs, possibly over a network)
    * Revisions and versions (as global labels for those snapshots)
    * How Subversion does copy-modify-merge
      * Working copies
        * copy: how to get them (checkout)
        * modify: how to change them (with an editor and svn commands to be
 described in detail in chapter 2)
        * merge: how to submit your changes (commit)
      * Mixed-revision working copies

 As you can see, I'm aiming for a certain parallelism here.

-- 
Ticket URL: <http://svnbook.red-bean.com/trac/ticket/98>
SvnBook <http://svnbook.red-bean.com/>