On Tuesday, July 30, 2002, at 10:24 AM, Karl Fogel wrote:
> Scott Lamb <slamb@slamb.org> writes:
>> Why?
>>
>> This information would be helpful. These are particularly important
>> when using SCM systems. Subversion now is getting relatively
>> experienced users who have used CVS, were dissatisfied, and are
>> willing to be on the bleeding edge to get something better. But
>> post-1.0, there will users who have never used another SCM system and
>> are not familiar with these ideas.
>>
>> The chapter could be called "Good SCM Practices" to clarify it is not
>> Subversion-specific.
>
> A brief rant:
>
> The challenge in writing documentation is deciding what not to
> include. Technical books typically run *over*, not under, their
> projected page count.
Three reasons, having been a tech author of a best selling book (this
was back in 1996 though).
1. They want page counts when you do the outline, before the book is
ever started. People tend to underestimate how much they can write for
a given chapter to compensate.
2. You get paid for the number of pages you turn in, not the number of
pages they want.
3. If you do overestimate a page count, they want that many pages
anyway, no matter what, and you are forced to include all kinds of crap
to meet it, even if it is useless and makes the book suck.
> If we're not careful, we'll have an enormous
> doorstop in which casual browsing is punished by acres of off-topic or
> redundant material. (Sound familiar? Sound like a lot of technical
> books you've seen? :-) ).
>
I wouldn't worry about this, unless you think that we can't draw a line
somewhere.
You can put it in the appendix, and thus, casual browsing isn't
affected.
> Good SCM practices are completely independent of Subversion. You can
> use SVN without good practices. You can have good practices and yet
> not be using SVN.
>
> Let's please keep non-Subversion material out of the handbook.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Tue Jul 30 17:15:19 2002