I had hoped to have the time to provide some more extensive comments, but
unfortunately paying work had to take priority. But here are some initial
reactions, along with one nit. I've placed the more objective points first,
with the more opinionated stuff later.
The nit first, because it's trivial. In Chapter 1, A Quick Start, there's
an example that shows
$ ls /path/to/repos
conf/ dav/ db/ ....
It should be ls -F, because standard ls doens't show the trailing / on
directories. True, many people may have it aliased that way, sometimes
without even being aware of it, but it's better to be precise.
More general structural comments (way too late, but perhaps the next
edition):
1. The HTML version, at least, often says "see the section called ...." I
really hope that it doesn't appear that way in the print edition. It looks
like an artifact of the software that processed the book sources, but it's
really bad.
2. The Subversion's Components section in chapter one lists several items,
such as svnversion and svndumpfilter that don't show up in The Complete
Reference chapter. Indeed, snversion doesn't seem to show up anywhere else,
while the svndumpfilter reference info, and some others, is in the
Repository Administration chapter. It's not that I want to take "Complete
Reference" overly literally, but that I think such information really does
belong together in the reference. (In other words, you can't fix this by
deleting the word "Complete" from the title of Chapter 9.)
3. There are a number of places where you do a very good job of presenting
alternative approaches diplomatically, but the Lock-Modify-Unlock vs
Copy-Modify-Merge model isn't one of them. This is going to look silly,
given that locking is the very first item on the post-1.0 list. But even
worse, you don't really do justice to the discussion, nor should you. I
know from reading this list that you're familiar with many of the issues and
approaches that underly these two approaches, but that doesn't show up in th
is part of the book. The end result, I fear, is that anyone familiar with
concepts such as advisory locks, or with good experience using locking
models (i.e. ClearCase, whose popularity belies the strong criticism of the
locking model), will simply read this section, decide you're not as familiar
with the subject as I know you are, and disgard the book and subversion.
But there's no reason for you to even get into this discussion. This is a
book about subversion, not about version control systems in general. The
fact that the copy-modify-merge model is popular is all the justification
you need here. Just don't raise the issue at all.
4. I really hate the overuse of the term "use-case" in the manual. The
term is being overused everywhere, to the point of becoming a fad that
dilutes and obscures its original meaning.
Use-cases are a requirements technique. They are applied before defining
the user interface or designing the product. As such, they're written
before things such as command line syntax come into existence, and are far
more abstract than what you have. True, they're a good place to start for
writing user documents, but the label doesn't come over (just like you can
use BNF as a basis for a reference manual, but you can't describe the
reference as a formal syntax). What you have can, at best, be described as
the way subversion solves particular use-case problems.
But please, stop using the term altogether. The more people keep using the
term outside of a requirements process, the less valuable it becomes, and
we'll be back where we were fifteen years ago, when requirements engineering
was an obscure part of software engineering that few developers understood
or cared about. (I like Ambler's brief paper at
http://www-106.ibm.com/developerworks/webservices/library/ws-tip-docusecase.html
as a good online description of use-cases, but there are many others.)
Regards, keep up the good work, and notwithstanding these comments, I hope
the book sells well,
Gary
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Received on Fri May 28 20:03:30 2004