New User Confusions; Docs Ideas

OK, I am slowly ... very slowly ... getting my head around the
"Subversion way".

My particular concern at the moment is understanding (a) when commands
affect the repository, the working copy, or both, and (b) what I can do
using standard file management commands in the working copy without
confusing Subversion. I know the former is documented but it is very
confusing at first. The latter I can't find -- is it discussed
somewhere? If not can someone explain it?

My latest example is that I was trying to change the name of a
directory. Should I be able to do this with a plain old svn move?
With a move plus a commit? Suppose I change the filesystem name first,
can I tell Subversion about it later? Or do I have to use subversion
alone to make changes?

I will say, with no disrespect intended to those dedicated folks who
wrote the docs, that to me these are examples of a general malady --
the same one my own software product docs had when I wrote them: These
things are (presumably) crystal clear if you already know what you are
doing (meaning, you already figured out the basics of Subversion, or
perhaps of CVS). If you don't, there are way too many mysteries. In
other words the docs, despite the careful explanations of basics, work
far better as a reference source (for which they seem excellent) than
as a learning tool. I think this problem is often inherent in docs
written by people deeply involved in a complex technical project, that
certainly was the case when I was the writer on my own projects!

To be more specific, I think part of what's needed is not to assume
such a good understanding of the details of how Subversion works and
the meanings of the terminology in describing the individual commands.
The user may have read the earlier discussions but most likely has not
fully absorbed them, and will make mistakes. The errors -- which tend
to be things like "x is not under version control" or "Out of date:" --
are very hard for a new user to sort out, in the sense of knowing what
to do to fix them.

One alternative would be to add a bunch more scenarios for common
tasks, and more detailed notes on what id going on, which would aid a
tecnically competent user new to Subversion and its mindset (i.e.
someone like me :-)) to learn by example. For example, the following
item under svn move would have helped me a lot -- though I still don't
know which of the items in [], if any, is correct :-):

    Rename a directory in your working copy:

    $ svn move olddir newdir
    A newdir
    D olddir

Note that the directory move [will be done immediately in the working
copy] [will not be done until you do a commit, at which point the
directory name will be updated in the repository as well]. You
[should] [should not] create the new directory before doign an svn
move, as Subversion [will not] [will] do it for you.

Some examples of typical wrong commands, with the error messages they
produce and the changes needed to make them work properly, might also
be very helpful to new users.

Thanks,

--
Tom
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org