Changelist analogy confusing

C. Michael Pilato cmpilato at
Thu Sep 4 13:11:15 CDT 2008

James Kistruck wrote:
> Michael,
> That looks good, thanks.
> On your change log:
>> Tweak some wording to avoid implying untrue things only revealed as
>>   untrue if the reader keeps reading long enough to hit the
> revelation.
>>   . o O ( Huh? ) 
> These two sections seemed odd to me precisely because I didn't read the
> docs in a linear manner.  I read around a bit, and then went back to
> read it properly.  Maybe these sections weren't meant to be reference
> material in that way, but as they are so easy to read I have come back
> to them frequently.

In general, we want the book to be digestable as a reference.  Clearly, we
can't make every section explain every fundamental concept.  Nor can we
litter the pages with cross-references to other book sections.  We've had to
try to find that balance between saying too much and saying too little.  I
suppose I kinda hope that most folks will either read the book straight
through once then use it as a reference thereafter OR already be familiar
enough with Subversion that they are literally seeking only specific
reference information (command-line syntaxes, configuration directives and
their meanings, etc.)

C. Michael Pilato <cmpilato at> |

"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