Review of Chapter 6: Server Configuration

C. Michael Pilato cmpilato at red-bean.com
Sat Feb 24 19:23:34 CST 2007


Ben Collins-Sussman wrote:
> On 2/23/07, C. Michael Pilato <cmpilato at red-bean.com> wrote:
> 
>> I really, really don't like how the chapter starts off.  Right off the
>> bat, "Table 6.1. Network Server Comparison" slams readers with all kinds
>> of industry and Subversion buzzwords before they even have a chance to
>> get acquainted with what a Subversion server is and provides.  At the
>> very least it should be moved down into the "Choosing the Best Server
>> Configuration" section.  The list-filled sections "The Apache HTTP
>> Server", "The svnserve Server", and "svnserve over SSH" all tell you
>> things you might want to know when trying to choose which server to
>> implement.  But they precede the section called "Choosing the Best
>> Server Configuration".
> 
> Just to give you a background on the rationale for the current structure:
> 
> For our first edition book, we only had the simple table that lists &
> compares server features.  The only text accompanying the table was
> something like "here are the facts, now choose whatever server is best
> for you."
> 
> For years, I've been getting criticism from users@ and #svn about
> this.  They say that this table isn't friendly enough.  The typical
> feedback was "yeah, the table is really useful, but it still doesn't
> tell me which server to use;  I want a human being giving me personal
> recommendations, explaining tradeoffs of why I might want (or not
> want) to use a particular server."   It sort of ties into our 2nd
> edition theme of "recommend best practices."
> 
> So my response was to leave the feature comparison table as is, but
> then add a bunch of 'human' analysis afterwards.  Why would you want
> (or not want) to use a server?  What do we personally recommend for
> specific situations?
> 
> That said, I'm very much open to your re-structuring suggestions.  :-)

This all goodness.  I don't dislike the table.  I just don't like its
location.  [Read on.]

>> I think the little bit of text that's in the "Overview" sect1 should be
>> worked into the chapter introduction.  There's precious little detail
>> there, and we shouldn't need a section called "overview" when that's
>> what the chapter introduction is actually for.
> 
> But you've lost me here.  You've now twice expressed frustration that
> we're not giving enough general information about servers, but I don't
> know what this information would be.  At the moment, we present these
> bits of info:
> 
>  - we're going to explain how to make your repository available over a
> network
>  - svn has an abstract network layer with 2 current implementations
>  - one server is apache, which speaks HTTP, the other is svnserve,
> which speaks a custom protocol.
> 
> What other information would go into a chapter introduction?

I wasn't trying to say you should write more for the chapter intro.  I
was saying that the couple of paragraphs between the "Overview" title
and the comparison table could move to *before* the "Overview" title.

But now I'm not so hot on the idea now.  [Keep readin'.]

> So how about we meet halfway?  Lemme try this:
> 
>  * Expand the introduction a bit more (if i can?!)
>  * Show the feature table
>  * Present the personal recommendations (based on the feature table)
>  * Put the why/why-not lists as subsections of the recommendation
> section, as you suggest.
> 
> I'll do this in a forthcoming commit.

I think the key to expanding the intro is simple.  The comparison table
 is useful, but is an unfriendly way of introducing features.  Use prose
to talk about each server, and briefly explain what it offers.  In other
words, pull the stuff out of the table and into the prose in a general
introductory sort of way.  Then, let the table repeat the features and
attributes for the purposes of comparison.

So, here's my counter-proposal:

  * Overview
      texty texty
      feature table
  * Choosing a Server Configuration
      intro blob
      why/why-nots
      summary (personal recommendations)

> Along that line, you're right, it's odd that the why/why-not has 3
> categories, and everything else has 2.  But to reconcile that
> difference, my instinct is to move everything to 3, not to 2.  I think
> it will make things clearer to administrators -- rather than focus on
> "2 servers", we focus on "3 use cases".
> 
> Maybe I'll just make the fetaure-comparison table into 3 columns,
> rather than 2, so it's clear that the table is about use-cases, not
> executables.

I think your instinct is good.  "Make it so."

> Ah, good idea, I've renamed the whole section to "Tunning over SSH",
> since that's what it's really about.

I hope you mean "Tunneling".  :-)

But, must it be over SSH that you tunnel?  Could you not tunnel over
generic RSH?

-- 
C. Michael Pilato <cmpilato at red-bean.com>

"The Christian ideal has not been tried and found wanting.  It has
 been found difficult; and left untried."  -- G. K. Chesterton




More information about the svnbook-dev mailing list