Fog Creek Software
Discussion Board

Do I need a help file

RefMate is finished.

Well, I am still finishing the website, and the documentation. However the coding side is done.

How much documentation do I need?
Do I need to create a help file? My program is very small, I have done my best to make it fool proof, however I have heard rumours about bigger fools....
I don't want to create a help menu that doesn't help.

I am afraid if I start writing a help file it will be full of unhelpful points just to make the help file look reasonable, to make the contents look full etc. When really what I think would be most helpful would be a link to an FAQ on the website.
My reasoning is this:
- So far I haven't had feedback that suggests anybody has had any problems at all with the program. I had a wide range of students look at it, they found bugs, but didn't ask any 'help' questions. Well maybe one.
- I don't want to write an entire help file full of 'filler' stuff just so that the answer to this one problem doesn't look lonely.
- I am sure there will be more issues, an FAQ page is more dynamic

Does anyone have any thoughts on this?

Aussie chick
Friday, August 6, 2004

Sounds good to me. I have programs that link to the website for documentation. There's no reason that the documentation can't start as a FAQ.

Question: Do you expect everyone who uses your software to have an internet connection?
Friday, August 6, 2004


C O N G R A D U L A T I O N S ! ! !

on finishing RefMate.
Friday, August 6, 2004

I don't know if I expect them to have an internet connection.

I think that most people have internet connections today. (let me clarify I think most university students in Australia have access to an Internet connection).

I don't expect that the user be connected to use the program, however I don't think that it is too much to ask that they go to a website for the FAQs. I could help by ensuring that the formatting of the FAQs was printable/downloadable. ie include an uptodate downloadable *.doc file.

Aussie chick
Friday, August 6, 2004


Aussie chick
Friday, August 6, 2004

I think a FAQ combined with a support forum would be ideal. It would be a great way to get feedback on the product.

Did you/will you do a beta test period? Question may come up during this that you can add to your FAQ.
Friday, August 6, 2004

Yes I did some beta testing a few months back.

This ironed out some bugs, and probably bought in one or two real 'questions' that could be used in the FAQ.

Yes, I would like to implement a support forum too.
I do have a forum already (which I used for the beta testers), however it requires registration and all sorts of fun stuff.

A forum like this one would make an excellent support forum.

Aussie chick
Friday, August 6, 2004

Yes, it certainly helps that you can ask a question easily, and without registering.

I assume you're on a bit of a deadline, it being August already. Just set up a support forum, and link to it from the Help menu.

I don't know how simple/complex your software is, but it should have *some* sort of instructions. Why not combine a tour & instructions? It's a selling tool when it's on your website, and it's a "how to get started" when it's bundled with the product.
Friday, August 6, 2004

Yukko, can you tell I don't like writing documentation?

Yes a tour of some sort would be good for both the reasons you described. I hadn't htought of it, but now I find it hard to refute.

The software is pretty basic. Only one form.

Aussie chick
Friday, August 6, 2004

Oh yes, I remember looking at your software a few months back. Just do a couple of screen caps and put a description for each of the items in the screen cap, and do a high level overview of the concept, and then link to the forum.

Starting with the screen cap should give you something to start with. It shouldn't take more than 15 minutes, but if you get into it, you can spend as much time as you want.
Saturday, August 7, 2004

I think in another time and another place AussieChick and MarkTAW can be a good husband and wife.

John Howard
Saturday, August 7, 2004

Where are we eating dinner?
Saturday, August 7, 2004

* (In another thread AussieChick said that all Americans she knows only care about where they're gonna eat dinner.)
Saturday, August 7, 2004

no vegemite please

George Bush
Saturday, August 7, 2004

I was going to do curried sausages and mashed potato.

Aussie chick
Saturday, August 7, 2004

Sounds good to me. Just as long as it's NOT at the Hard Rock Cafe, I'm cool with it.
Saturday, August 7, 2004

One suggestion, you may want to bundle a version of your FAQ, or Tour or whatnot with the product so no internet connection is required.  Then, you could also have a link in the product to "Visit Current Documentation" on your website.

Also,  I think the best way to document is through usage examples, rather than just  an index with random information.  For instance, come up with a list of features, and then show examples of each.  This would be both a tour and help doc as Marktaw stated.

Good Luck.

Saturday, August 7, 2004

Yeah... That's what I meant. Bundle it with the product & then provide a link to the forum. Sorry if I wasn't clear. :-)
Saturday, August 7, 2004

The thread seems to be converging - could I ask how about a Help button to bring up the annotated screencaps, lead on to docco (FAQ and examples), show links to online support/forum *and* display your copyright notice?

Could be done using what you've used so far, in html or, if you're into some pain, MS Help Workshop or somesuch.

(Aside -when I moved my product documentation into help I found many poor design choices most of which were fixed by changing the interface to what could be explained in help. So next time,  help will evolve alongside the code).

Your utility looks the bee's knees and deserves to prosper. (I have 3 students right here who should be interested.) 

However you sell or distribute, it's pretty essential to have your contact details and copyright notice right there *in* the code so as it's passed around folks will know it's you and how to pay.  Have you researched the selling process? Could be one of the better thread sequences ...

Please let us all know when it's available.

Sunday, August 8, 2004

A few comments.

A good help system should not just give help on using the program, but also about the general domain of the program. So in your case, ideally the help system would teach students about bibliographies in general. Where to find guidelines for styles. Where to search. What to do when you want to cite a web site or conversation rather than a journal article...  My software does statistics, and I'd say 90% of the help and manuals is about stats, not the program itself. (This is probably a version 2 thing for you.)

As you think about your help, think about two kinds of people. One kind (those on this board) want to be told what a program does, what its limiations are, how its data are structured. Once they "get it", they'll figure out which keys to press. The other kind wants to follow examples -- to be told exactly what to do with screen shots to reassure that they are doing it right. From detailed examples, they generalize to doing other things with the program.

The Windows Help system is an ok solution for failry complex help needs (but far from perfect). Maybe you can get by with  buttons on your dialog that say "help" or "Explain" or "More info" that popup a second dialog with a paragraph of explanation.

Don't focus only on help using a particular dialog. Also help people figure out the scope of your program. Help the person who is trying to save their bibliography to a database, or is trying to make a database of videos, or trying to import their bibiolography already formatted as an excel table...

Good luck!

Harvey Motulsky
Sunday, August 8, 2004

We have a very limited help file in our 20 programs.

One has a big heading at the start that says :

"thanks for reading this. Please let us you know you read it and we'll enter you in a prize contest".

NO ONE has EVER mentioned the above. I don't think anyone reads the help. Programs are designed so that reading a manual/help isn't necessary.

We do have a toll free tech support line to guarantee that they truly don't need help. VERY few people ever call that.

Sunday, August 8, 2004

*  Recent Topics

*  Fog Creek Home