Other Software > Developer's Corner

Style guidelines for how to structure helpfiles?

(1/5) > >>

daddydave:
I was wondering if anyone had any suggestions, pointers, or good examples of best practices for organizing a help file. My Google fu fails me...

EDIT: Did find this from searching delicious:
http://www.uxmatters.com/mt/archives/2007/05/the-anatomy-of-a-help-file-an-iterative-approach.php

Paul Keith:
As a non-developer, I think generic help files are growing outdated.

There may be some things that specifically in need of a help file but generally you want a screencast or a demo page. (i.e. a notetaker that has introductory texts already exposed in the lay-out of the program when a user opens it)

I think your best bet though is to narrow down the purpose of your program and then do a search for similar programs that are popular in Delicious and then compare their help file lay-outs with your own.

Generally I would think the important part is to narrow down the search and the actual guide. Everything else is secondary even the structure although that is where having your program be able to support the help in it's structure rather than having a separate section helps.

If worse comes to worse, you could look at how DC is organized as a forum. This should apply even to offline help files.

daddydave:
There may be some things that specifically in need of a help file but generally you want a screencast or a demo page.
-Paul Keith (July 07, 2010, 04:35 PM)
--- End quote ---

Interesting thought. As someone who is a user 99% of the time, I will tend to watch a screencast as a last resort if the helpfile is absolute crap.

EDIT: In fact, the way TaskDaddy evolved, the program that was the inspiration for it had some help text on the dialog itself, but when I tried to do that, it seemed like an intimidating amount of information, so I put a blurb saying to press F1 to view the helpfile and also a help file icon. (see the screenshot by clicking the TaskDaddy link in my signature.) Probably not the best thing to do, but it was all I could think of at the time.

I think your best bet though is to narrow down the purpose of your program and then do a search for similar programs that are popular in Delicious and then compare their help file lay-outs with your own.
--- End quote ---

I think I'm coming to this conclusion as well.

Paul Keith:
I think a screencast is the first resort for many people because it is a combination of introduction + help file.

There are some programs though that don't require full-on screencasts but rather an animated demonstration on your landing page.

I think Taskdaddy falls into those categories.

I'm not really sure why you see that as "not the best thing to do" as the only way I could see it being better is if the dialog itself was inside the search box to make it even more minimal. (I'm mostly referring to web services though)

I could see what you mean though if you're referring to this as being overwhelming for a help file: http://www.outlookcode.com/codedetail.aspx?id=1642

I wasn't able to actually open the .exe because I didn't have Outlook but from my personal viewpoint, it's not the structure that's the problem but how you have to read the help file itself that complicates things. (Most people initially using TaskDaddy probably wouldn't read the help file as much as head straight to the syntax, skim the right section for their needs and head back to the program immediately)

My specific suggestions would probably be to copy the lay-out of this page and rename the syntax label to "keyboard syntax" or something casual sounding like "symbols" (although "syntax" might make it more professional sounding depending on the user - I'm mostly thinking of the way some help files name keyboard shortcuts as "shortcuts")

http://www.rememberthemilk.com/services/smartadd/

Next...

Drop the interface label for an "advanced" folder and add the label "command-line" to describe how to install/enable the command-line interface.

Then add another label titled "syntax" and insert the explanation for the command-line syntax.

For the interface pictures, I would suggest adding those to the intro below the description.

Put "Tips" in a separate label under advanced.
--- End quote ---

This is just for how I would change it though but the best advice should come from users of the program itself.

Some other minor things I might change if I know how to code:

* change text to "press F1 for help"
* drop either the help icon or drop the definition
* make a show help-file pop-up on inital open (with a checkbox for making it appear again or not) - so that you don't need to tell the user to type on the textbox
* link the help icon or F1 to the syntax page instead of the intro if you haven't done so already

daddydave:
Thanks for the very specific suggestions! Much appreciated. :Thmbsup:

Navigation

[0] Message Index

[#] Next page