There are so many ways that the above software quote-unquote "information" box is just plain baaaaad. But before I itemize its sins, allow me to offer a quick primer on what the software is supposed to accomplish. After all, I don't want to perpetrate its wrongs on my gentle reader.
Programmers are as capable of messing up computer files as anyone, partly because they're more dangerous to begin with. So the concept of "source control" was invented. Source control allows you to store previous versions of code (or other files) for safekeeping. If the programmer messes something up beyond all recognition s/he can simply roll the file--or, more likely, files--back to a not-messed-up version.
Different species of source control software have different methods of saving/retrieving files. One requires that the source control program be started before files can be checked in and out. Another works through the Windows Explorer you're probably used to. In this case, the programmer merely opens the folder that contains the file(s) in question, and the source control program's options become available when s/he right-clicks the files/folders in question.
Normally, I'm used to working with the first species, and normally get into trouble if I try to use anything other than the most basic functions of the second. But this morning, I needed to do something that wasn't basic, something that had more to do with setting properties of the software itself. (I wasn't too worried about mistakes b/c I knew I'd have the option of blowing away the consequences of any misunderstandings.) So I made my first mistake of going through the Windows "Start" menu. That triggered the message. As used as I've become to bad documentation, that one managed to find a chink in my armor.
Let's take it sentence-by-sentence:
"TortoiseSVN is a shell extension." Good for it. Here's a cookie. But it's running on Windows, which means that novice programmers--who probably need source control more than any other kind--might just not know what that means. That cardinal rule of writing, "Know Thy Audience?" FAIL. And the little joke baked into the product name--Tortoise...shell...get it?--isn't worth wasting precious space or the damage done to the first impression of the product.
"This means that it is integrated into the Windows explorer." Leaving aside the condescending tone of "This means..," this sentence is more likely to send the new user to the Windows "Start" menu to launch Windows Explorer and spelunking the menus for "TortoiseSVN" options that don't exist. The "Write so that you can not possibly be misunderstood" rule took a bruising here. (Oh, and btw: Windows Explorer is a trademarked product name, and should be marked as such, just to stay on the good side of the Legal Dept.)
"To use TortoiseSVN please open the explorer and right-click on any folder you like to bring up the context menu where you will find all TortoiseSVN commands." Now, we've finally been told something useful. The problem is that it should have been the first thing a new user reads. The "Put the most important information at the beginning of the paragraph" rule was likewise clobbered here.A hyperlink to the manual is useless if clicking it doesn't open it in the user's web browser. Windows dialog boxes don't even allow you to copy text--a real limitation when you're a programmer trying to debug error messages--much less launch your web browser.
"And read the manual!" So...where is it? TortoiseSVN doesn't act like a "normal" computer program--that's just been demonstrated. Ergo, there's no "Help" menu. If the user just now downloaded and installed the program, s/he would very likely still have the browser window open and would just search the website for documentation. But any programming dept. that requires source control will insure that it's used by pre-installing the software. That leaves the user with the extra step of Googling for the documentation...something that should be placed at the first user's fingertips. Particularly if it's important enough for an exclamation point and underlining.
Rather impressive, the amount of documentation rule-breaking that was packed into just a few square inches. But my point is not to traduce the efforts of someone who probably spends most of her/his time writing code rather than documentation. My point is that you don't even have to be a professional writer to create something useful for the people who use your software/widgets/whatever. If you can look at your handiwork through the eyes of someone who's never before seen it, you are already ahead of the proverbial pack. Draw up a list of the absolute minimum amount of information those (intelligent but under-informed) folks need to know to be effective. Then prioritize it (in order of importance to them), and write. Everything else is merely spell-checking and proof-reading for grammar.
No one expects literary merit of any technical documentation. Heck, one of the most revered works in the software profession is written in a style that makes me grind my teeth. Understanding precisely who your user is and making it nearly impossible for her/him to screw up will make up for any number of stylistic sins. Trust me on this.
