trlists@clayst.com writes:
> 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.
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. 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.
> 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 :-):
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.
Best,
-Karl
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Received on Mon Nov 29 20:31:34 2004