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