Thomas Hruska wrote:
> Good for you. I happen to be a __very__ slow reader probably because I
> memorize just about everything I read. Most people are done reading a
> chapter or two while I'm still reading the third page for the second
> time.
I feel sorry for your handicap, but that's hardly a good reason to
blame the TSVN doc authors for your problems. I'm sure that if you
could instead come up with some constructive criticism and concrete
suggestions on how to make the docs more accessible to the less abled,
the authors would be happy to discuss any proposal with you.
> With technical documentation, my approach is to hierarchically
> analyze the content from chapters titles and subtitles and pick and
> choose what to read based on what I want to accomplish because reading
> the entire documentation would take me a week and most technical
> documentation is designed to NOT be read like a book. In this case, my
> strategy failed because the naming schemes of the titles didn't follow
> traditional technical documentation methodology.
If your approach only works with _some_ technical documentation, then
it's not a very good approach now, is it? How about amending it with
a new first step, entitled 'Glance at the size of the documentation
and consider whether it's so concise and well-written that I don't
need to structurally analyze it but can actually get over with reading
the lot of it in half an hour'?
> I did _eventually_ find everything in a section labeled something I
> considered to most likely be an "advanced" section. I never bothered
> to expand it until after sending the original e-mail because I had mentally
> labeled it to be an "advanced" topic in the documentation. If I did that,
> you can bet your britches that other people do too.
Why would "Daily Use Guide" sound to you like an advanced topic?
> The documentation is "okay".
No it's not. It's absolutely /magnificent/. It tells you everything
you need to know about Subversion in about half an hour. Concise, to
the point and well-written. It's the best darn piece of technical
documentation that I've ever read, period.
> There could be more of the cool real-time
> animations like that one I saw in the Appendecies, but adding an
> introductory tutorial to the website that guides the first-time user
> through the entire download, installation, and setup process would be
> terrific.
It's an open source project. If you can produce a piece of quality
work, I'm sure it will be accepted for the TSVN web page, pronto. And
if you produce a piece of crap, I'm sure that the project maintainers
will let you know in a more polite manner than I'm capable of in what
will seem to you like split seconds.
Here's some past discussion which you might find helpful (be sure to
read the whole thread, not just the first message).
http://tortoisesvn.tigris.org/servlets/ReadMsg?listName=dev&msgNo=20641
> There could also be a really nice wizard that guides the user through
> setting up a repository and then have another wizard to import a
> project, rename the directory, create a directory of the same name, and
> then checkout the project. Then I wouldn't have had to read the
> documentation.
Great idea. Sounds like an entirely different beast than TSVN, but
useful additions like this are probably welcome as a separate
executable file to be installed alongside TSVN. Try cooking something
up and submitting a patch.
> Now this is probably be "heretical" to all the open
> source people here, but I can't think of a single _normal_ person on the
> planet who honestly WANTS to read technical documentation. A good rule
> of thumb to follow is: If someone has to open a help file for anything
> other than really advanced features buried 3 or more dialogs deep, then
> something's wrong with the product itself - no matter how good the help
> file is.
Not at all heretical, but you are barking up the wrong tree. I can't
count the times that Stefan has put hard work to the table to make
TSVN easier to use by forging features that he never touches himself.
TSVN does it's very, very best but is sometimes limited by the
underlying Subversion libraries that it utilize.
On a more general note, once people has learned to use a piece of Open
Souce software themselves, they seldom have the motivation or the time
to fix those things that bugged them when they were newbies. I know I
have a couple of items on my TODO list to improve (T)SVN for newbies
and for people using shared code like you, but so far it hasn't been
critical enough that I could use work hours to work on it, so they've
been sitting there for a while.
I'm looking forward to see if you put something concrete on the table
(but it's definitely not my place to criticize if you don't).
> We'll see how it goes when I go to create my first tag...
Here's a good way of tagging:
1. Make sure that your version tags in your source code trunk says
'x.y.z.devel'.
If someone accidentally installs or releases from trunk, you'll know.
2. Create the tag (really, a copy) in your working copy, not on the server.
3. Modify version numbers in your tagged code using SubWCRev or by hand.
4. Pin externals in your working copy tag to point to the current
revision (-rXXX).
5. Commit your tag.
> I've noticed rollbacks are different in Subversion and that two types of
> rollbacks are possible but only one is available (the other requires
> using the command line). I made a few mistakes on my first import that
> would have been nice to permanently remove. Not a big deal, though, but
> I am a perfectionist...even my Subversion checkins have to be perfect.
FYI, in SVN terms it's 'reversion' and 'obliteration'.
There's a discussion on the SVN mailing list right now about
obliterate which you might want to take a look at.
> I just tried the svn:externals approach and that creates a copy of
> CoreLibrary in each project's directory. CoreLibrary is huge and I'd
> prefer not having it duplicated everywhere, but what SVN is doing makes
> _some_ sense at least for previous versions. For the current version,
> however, it doesn't make much sense to have the same code duplicated
> everywhere. I work on multiple projects and applications at any given
> time that all rely on the CoreLibrary project. I don't want to have to
> commit every change I make just to synchronize multiple copies.
In that case, simply put CoreLibrary in your repository side-by-side
with your projects. Then change the references in all your projects
to point to "../CoreLibrary/<xxx>".
How do you accomplish this right now, if not like the above?
> The problem could be solved with allowing relative directories via '..',
> but unfortunately svn:externals doesn't allow that.
If you only want one copy of your CoreLibrary, I'm not sure exactly
why you want to use svn:externals. Nevertheless, you can refer to a
parent directory just fint, you just have to use the absolute path in
the repository.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tortoisesvn.tigris.org
For additional commands, e-mail: dev-help@tortoisesvn.tigris.org
Received on Sun Oct 2 15:02:11 2005