On 29 Nov 2004 kfogel@collab.net wrote:
> In defense of the doc writers, I'd like to point out that there's a
> balance problem. You're right that the docs aren't great for version
> control newbies. However, had they been written expressly for
> newbies, they would be nearly unuseable for people who already know
> (say) CVS. Every documenter has to make a choice of audience, and
> compromises come with that choice.
Absolutely, I had to do the same when I was putting out a technically
oriented product. I totally understand. But I think perhaps folks
underestimate the degree to which there is a specialized terminology or
framework within which the whole thing is set. I'm not at all new to
version control, but I have not worked on open source projects nor on
the kind of large, widely distributed, multiprogrammer projects at
which CVS and Subversion seem to have been targeted. I find the
approach used in Subversion confusing, I think because the docs are
assuming a model that's not the one I'm used to. Part of my evidence
for this is that as I work to get my mind around that model I do
better. The individual commands are mostly very simple to understand
once you understand the model.
> Similar sentiments apply to the error messages, with the added
> pressure that one cannot generally write a long description in an
> error message -- short, identifiable strings are better in the long
> run, because they get quoted a lot in bug reports and emails.
Absolutely. The short error messages are fine -- what would be great
is some documentation on what they might mean. A sort of "what common
mistakes one could make that would produce this error" list. Of course
that's much more work than simply giving the technical meaning of the
error message text, or allowing the text to stand for itself.
> I can't stress too greatly how much we would love to have such
> documentation! We are a volunteer project, and any time you can
> devote to this end will be appreciated... If you want to contribute,
> but aren't sure how, ask here, we'll be happy to help you help
> Subversion.
That I understand, and I appreciate the "offer" :-). For now I only
know enough to be dangerous, let me get some more under my belt :-).
--
Tom
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Received on Tue Nov 30 02:42:45 2004