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. 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
We try to keep the docs a non-technical as possible. That's why it is
written more like a book. The real technical issues are either in those
sections as notes/warnings/hints or at the end of the docs in the
appendices.
> strategy failed because the naming schemes of the titles didn't follow
> traditional technical documentation methodology. 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.
You said before that you'd rather have that section labelled "getting
started". But that's not good either. Because you don't know from where
users start. I'd say most users don't have to set up a repository,
import data there but *only* start with checking out a working copy. In
those cases, an admin sets up everything and the users just have to
start working.
But then there's those users who first start with a local repository to
play around with Subversion a little bit, and those have to set up the
repository, choose a directory layout, import the data, ...
So we thought that "daily use guide" is a good chapter title: it has
everything in it you need to know if you're using TSVN from day to day.
But of course, we're open to suggestions.
> The documentation is "okay". 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.
I'm sure our doc people will take the hint.
> 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. 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.
There's a problem with that:
If we provide such a wizard, then the import command couldn't be used
anymore to import new data later on when the repository already contains
data. And that's something I do very often: every time I make a
tag/release, I then import the binaries of that release to that tag
folder (I do that in my office, not for TSVN).
> These are just suggestions on simple changes to the product that will
> make it infinitely easier to use. I've been experimenting with becoming
> a "user" of software over the past few months and try to mimic the
> average user wherever possible. I ask myself questions like, "What are
> my users going to think when they see this dialog?" "Is this static
> text intuitive?" "If I were an average user, would I read this?" "Is
> this error message meaningful to the user or is it nerdy?" I believe I
> am on the right track to creating higher-quality products, but perhaps
> it is the experimentation that affected my ability to read the
> TortoiseSVN manual....
We try that approach with TSVN too. But we're not always successful:
- If you make something too easy, you have to loose some advanced features
- Error messages are not from TSVN alone, but are thrown by the
Subversion library. We can't change them.
- We have to stick to the official Subversion terms, or we would confuse
those users who already know Subversion.
> TortoiseSVN is a decent product. It could be better in some areas, but
> once I got it up and running, it seems to pretty much maintain itself
> and appears to be easier to use than I remember SourceSafe being. We'll
> see how it goes when I go to create my first 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.
Do you mean 'reverting changes' with 'rollbacks'? I'm not sure which
rollback you can't do with TSVN - AFAIK everything that's possible with
the CL client is also possible with TSVN.
* The easiest way to revert changes from a specific revision (or
revision range) is to use the "Show Log" dialog, select the revisions,
right-click and choose "Revert changes from this revision".
* For more advanced rollbacks, you can use the Merge dialog and provide
the revisions/URLs there.
Stefan
--
___
oo // \\ "De Chelonian Mobile"
(_,\/ \_/ \ TortoiseSVN
\ \_/_\_/> The coolest Interface to (Sub)Version Control
/_/ \_\ http://tortoisesvn.tigris.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tortoisesvn.tigris.org
For additional commands, e-mail: dev-help@tortoisesvn.tigris.org
Received on Sun Oct 2 09:58:22 2005