I have to get my experience into this thread. I have been watching
with some bemusement as the comments at a rather detailed level
continue to move back and forth. Here's my experience with the
documentation.
1. I had never used any version control system before starting
to use Subversion at version 0.37. I just skipped over any
mention of CVS because it had no meaning to me.
2. I use the same policy with documentation as I did taking
exams a loong time ago in college: If the question was unclear
or I did not know how to answer, I went to the next question.
Then I would come back to those I skipped. This also works
with documentation-I take several passes over it over a period
of time. Unclear passages on an early pass are just skipped
and reviewed later if I need the info.
3. I made and remade the repository maybe 10 times as I sorted
out the documentation as well as a few bugs. I did not find
that unusual for software completely new to me.
4. We can strive to always use a term in only one sense but
after writing documentation for users of my software I conclude
that the meaning of a term is only partly determined by
definition. The user's past experience always sneaks in and
sometimes puts nuances on the term that I never thought were
there.
Conclusion: continue to strive for clarity but each user will
really have to experiment, crash and burn a few times, and start
over. Therefore do not start using a major new software
package on a critical project. Climbing the learning curve
usually takes more time than any of us estimate!
I picked Subversion over CVS because Subversion had documentation
that made sense to me and CVS appeared hopeless as well as dated
from my perspective.
A happy Subversion user but still learning,
Delbert
On Monday 20 December 2004 07:58 am, daniel@email.unc.edu wrote:
> I want to add a data point from a different perspective.
>
> I've been using svn for about 3 weeks. I've been using some type of VC for at
> least 10 years. I found the subversion book to be quite clear, though I do
> see how users new to VC coule be confused.
>
> The "repository" is whatever was given as the argument to "svnadmin create".
> A "project" is a filesystem tree containing related files and is an
> abstraction having meaning only to the users of the system.
>
> I am finding that my users are happiest with a "1 project per repository"
> mapping. My users think of a change in the version number as meaning
> "something has changed that I need to know about".
>
> Daniel
>
> > Quoting "Robert P. J. Day" <rpjday@mindspring.com>:
> >
> > On Mon, 20 Dec 2004, Ryan Schmidt wrote:
> >
> >> Perhaps it's also a bit confusing for the newcomer that the SVN book
> >> here uses "svn" as the name of an example project. When I set up my
> >> repository, it might not come as too much of a surprise that I named
> >> the directory "svn" ...
> >
> > that threw me the first time i read it as well. given that the
> > subversion per-directory admin dirname is ".svn", i just naturally
> > assumed there was something magic about the name "svn" as well at that
> > location.
> >
> > more generally, i think it's important to always label examples with
> > which parts have required, mandated names, and which names are
> > user-chosen and arbitrary. when it comes down to it, even the
> > directory names "trunk", "branches" and "tags" are flexible -- someone
> > else might choose to call them "main", "br" and "tg" for all i know.
> > not that i'd encourage that sort of thing, but it's stull useful to
> > know that those names aren't fixed in stone.
> >
> > rday
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
> > For additional commands, e-mail: users-help@subversion.tigris.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
> For additional commands, e-mail: users-help@subversion.tigris.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Received on Tue Dec 21 00:57:33 2004