Changelist analogy confusing

C. Michael Pilato cmpilato at red-bean.com
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 red-bean.com> | http://cmpilato.blogspot.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