Thanks for all the feedback on the help files guys. I found the comments and advice encouraging - I'm not really fond of starting the help file but once I get stuck in I'll see it through and maybe submit a URL so you everyone can check it out.
I experienced a disk crash Monday which really messed up my development. I didn't really see it coming but managed to make a recovery of sorts (Lost all my games, but who needs that!). So to all of you out there : MAKE BACKUPS OF YOUR SOFTWARE!!! :) Just thought I'd remind everyone how important those bits and bytes are to us in this development world. I was interested in what you mentioned about your source control utility Robert. I've been trying to figure out how CVS works and whether it is any good? I've worked with Visual Source Safe when I was contracting for another firm but since I started my own business now I don't want to fork out for license fees. Suggestions about versioning systems will be welcomed after recent experience with the crash. I have a Linux server in my office which I plan to use as a backup device, at this stage copying files to the box will be the extent of my versioning. ----- Original Message ----- From: "Robert Meek" <[EMAIL PROTECTED]> To: <[email protected]> Sent: Sunday, December 11, 2005 4:28 AM Subject: RE: Another Topic : Open to All to participate > I have to agree with Mike in that writing help files is akin to > doing the dishes or washing the car! It's a necessary evil however and > there are a number of things one can do to make the job a little less of a > pain in the arse. > For example, one can be very strict about commenting their source > code and then later use these comments to help remember salient points > they > might otherwise have forgotten. Me, I keep a working journal. It's part > of > a utility application I built for myself which first and foremost allows > me > to add a new project by name and version and then at the end of the day it > scans my project and other named directories and/or specified files, > creating a database record of my project. It's a poor man's version and > source control utility. And for each new record of the project it allows > me > to add an unlimited amount of text which I use to notate exactly what I > did > in that particular record and what I intend doing next. Along with notes > such as these I also add comments about use and if it is meeting my design > goals or not, as well as information I think is important to get across to > the user when I write my help file. > In any case, and no matter how you do it, I believe one of the most > important things about writing help files is that you keep good notes > while > writing the program, because you can never remember every point you need > to > make when you finally reach the time for writing one! > Second but just as important...lay out a structure for your help > file and then stick to it! One of my pet peeves is help files that read > like a cheap magazine, having you move from page to page just to read a > small article! Links are great but sometimes help file writers depend way > too much on them! Take a look at a well structured help file...one that > you > think makes it easy for you to scan thru as well as finding what you need > to > know when you need it! There's no copyright on how they are structured so > feel free to borrow from the best and then make an outline of the help > file > that will lead the first time user from the point of installation on > onward, > taking and explaining along the way each step in the program's use just as > you want the user to actually use it. This gives you more control and > provides the user with a sense of direction. The structure I use is > pretty common. I usually have three main topics in my help files...the > first being an introduction to the application which provides in a series > of > short sections what the application does, it's history if relevant, it's > installation, copyright and legalities, and last a developer contact > section. > The second topic is a series of individual steps, one per page > carefully entitled so the user can more easily find the section wanted at > the moment, and which is in essence a walk-thru of the application's > general > use. And I try to write this section using the same steps and in the same > order I designed the application to be used in. It's this section where > detailed descriptions and/or explanations are given, and where I add links > to each physical command from. Admittedly, this is the most difficult > part > of writing a help file and where I spend the majority of my time while > writing it! > The last section is the one where I add my lists of commands, > possible errors or problem troubleshooting, and any technical references > are > made. This section is not written to be read in the usual manner but is > provided as a series of information bits which I link to from the second > section as a reference only! > Finally, don't allow the task of writing a help file become > overwhelming! By keeping notes you'll get a handle on it early, and then > when you finally do sit down to write it, do so in small pieces...that is > as > a series of encapsulating topics...one per point you wish to get across. > If > you're already a decent writer then you'll have no problem and can do so > in > any free-form style you like, but if not, then write it as a series of > short, easy to read and understand topics that say ONLY the important > facts. > For example, I have a habit of being over-verbose, ( as you can tell from > my > message here. <g> ), so I can easily write a page or two about a single > button click! But no one wants to spend his whole day reading about a > button click so I've learned to simply provide a list of commands and the > various actions the user can take to initiate them. I state what the > command does, what controls initiate it are called, where they can be > found, > and what happens when the command is given. That's it! Then I break this > command list down into relevant sections, but still keep them all together > in a "Commands" topic, linking to each one from where ever else in the > help > file their use might come up! > Anyway, I hope this is of some help to you. Just remember we all > have to do it! > > from Robert Meek dba Tangentals Design > > > > __________________________________________________ > Delphi-Talk mailing list -> [email protected] > http://www.elists.org/mailman/listinfo/delphi-talk > __________________________________________________ Delphi-Talk mailing list -> [email protected] http://www.elists.org/mailman/listinfo/delphi-talk
