Ingo Adler wrote:
> Thomas Hruska wrote:
>
>> Yeah, I found it after hunting for 5 hours. I still think it is named
>> improperly or the sections are organized incorrectly or something. I
>> generally don't read documentation in a linear order...just the parts
>> that seem like what I need.
>>
> I don't think it's time to blame the TortoiseSVN documenters if it takes
> you 5 hours to find the next chapter.
>
> I'm very grateful that they invested much energy to create a document
> which I could can read from the beginning to the end. By the way, it
> took me less than 5 hours to read the whole document using the proposed
> sequence.
>
> Ingo.
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
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.
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.
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.
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....
Just a few thoughts anyway.
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.
--
Thomas Hruska
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tortoisesvn.tigris.org
For additional commands, e-mail: dev-help@tortoisesvn.tigris.org
Received on Sun Oct 2 02:44:47 2005