Author Topic: Style guidelines for how to structure helpfiles? (Read 15422 times)

daddydave · « **on:** July 07, 2010, 03:03 PM »

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...erative-approach.php

Paul Keith · « **Reply #1 on:** July 07, 2010, 04:35 PM »

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 · « **Reply #2 on:** July 07, 2010, 04:41 PM »

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)

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.

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

Paul Keith · « **Reply #3 on:** July 07, 2010, 06:35 PM »

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.outlookco...edetail.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.remembert...m/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.

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 · « **Reply #4 on:** July 07, 2010, 07:35 PM »

Thanks for the very specific suggestions! Much appreciated.

daddydave · « **Reply #5 on:** July 08, 2010, 05:56 AM »

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)
-Paul Keith (July 07, 2010, 06:35 PM)

Well, it's bad enough that a program is counterintuitive enough to require going to the help file, now I'm telling people the interface is so horrible they have to watch a movie to figure out how to use it. And with a help file ideally they can hopefully glance at it and get on with their work. You can't skim a video. In that way it is respectful of the user's time. That was my thinking, but I know not everyone thinks the same way, that's why I was asking.

I did have in mind to do a screencast, but mainly for the benefit for those trying to figure out what it is and whether it was worth downloading. And some how-to screencasts as well, but not as a replacement for the help file.

steeladept · « **Reply #6 on:** July 08, 2010, 07:05 AM »

Well, it's bad enough that a program is counterintuitive enough to require going to the help file, now I'm telling people the interface is so horrible they have to watch a movie to figure out how to use it. And with a help file ideally they can hopefully glance at it and get on with their work. You can't skim a video. In that way it is respectful of the user's time. That was my thinking, but I know not everyone thinks the same way, that's why I was asking.

I did have in mind to do a screencast, but mainly for the benefit for those trying to figure out what it is and whether it was worth downloading. And some how-to screencasts as well, but not as a replacement for the help file.
-daddydave (July 08, 2010, 05:56 AM)

This is my mind exactly. Screencasts as help files is the lazy way out because it never helps! It shows one persons' thought on how something should be implemented without a thought to my needs as the customer/user. I could care less about using fancywidget's video capabilities, yet that is all the screencast shows! No, it is a great marketing idea, but marketing and help are two totally different things.

My thoughts on help are in this order: 1) The UI should be intuitive enough that the help is unnecessary for 90% of the users. 2) The help should identify little known or little used nuggets, then explain all the possibilities and limitations of those options. 3) The help file should be intuitive itself (think tooltips or intellesense from VisualStudio). 4) It should be integrated into the product - not an add-on and not a website. 5) It should direct you to further information (usually a forum) for those things that were not thought of. Ideally, it should also be updateable as part of a patch to add those things found from the further information source.

Paul Keith · « **Reply #7 on:** July 08, 2010, 07:26 AM »

Marketing is help in the age of application overload.

It not only helps with discovery but most of all, it helps save the user time in figuring out whether the application is really for them.

Best of all, it helps the developer himself understand how best to help not only the users who have his perspective but especially those who don't see it the same way he does.

Which is the point of help - you want to help those who see through your eyes via the interface and you want to help those who don't via a screencast so that they can actually see how you see the application as.

It's actually lazier to not add screencasts when you can afford to because guess what? Adding screencasts doesn't remove you from the responsibility of doing all those other things like intuitive user interface.

If anything it encourages you because you don't want to be that person designing an orange painted car in a car show and have all that eyes think "scrap metal".

Similarly with a screencast - get lazy with either the interface or the screencast and it's pretty clear someone got lazy compared to the laziness hiding beneath the post-downloaded user who now needs to take some extra time figuring out your application and then uninstalling it.

I think what you guys are referring to instead are "guides". A guide can choose to leave or help someone depending on their bias. They are there to help but it's like a manual - it's there to help by being there.

...but there's a higher level of help.

That said I'm being hypocritical just so you know.

I'm the type of guy who tries to listen to people help me improve my writing style...and I listen...and I listen... but I just can't quite succumb to their perspective without losing the content of what I wanted to write so I hope you guys understand that this isn't me saying you're wrong, just providing a perspective that just as I should add more images in my posts - maybe you guys can find it in yourselves to try to discover a screencast structure that sticks true to your interpretations without blocking out those people who need help via a screencast.

daddydave · « **Reply #8 on:** July 08, 2010, 07:41 AM »

http://www.remembert...m/services/smartadd/
-Paul Keith (July 07, 2010, 06:35 PM)

is a really good example of the italicized part below.

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.
[italics mine]

Gives me too many ideas of how to improve what was supposed to be a quick and dirty script

EDIT: That is, it's not only a good example of documentation, it's a good example of having interface hints pop up helpfully but uninstrusively so that you don't need to go to the documentation.

steeladept · « **Reply #9 on:** July 08, 2010, 08:28 AM »

Never saw that before, but it is very similar to how intellesense works in Visual Studio. That is exactly what I meant by that. Of course no one ever said it would be quick and easy

mouser · « **Reply #10 on:** July 08, 2010, 08:33 AM »

i think screencasts are really useful to show someone if the application is going to be useful to them.
and doing a bunch of short ones can be really helpful to demonstrate features.
but i think a help file satisfies a real need, and can be useful for the author as well, as documentation of what the program does.

iphigenie · « **Reply #11 on:** July 09, 2010, 01:59 AM »

Screencasts are good marketing, they get you thinking "oh cool" but they are not good help/reference

In fact they are on the useless side for help:

screencasts are not searchable
the pace is slow
I can't jump to the one bit that I am interested in

All are scenarios where you go to the help section or FAQ

Heck even for image manipulation programs I have rarely seen a screencast be more useful than well annotated screenshots... I'd say never, I can't remember of one, but there must be some cases

Paul Keith · « **Reply #12 on:** July 09, 2010, 04:04 AM »

screencasts are not searchable

False. There are users searching for someone to show them how to work an app rather than a specific feature.

One can argue that a well designed app shouldn't need that but then one ignores how something as common and design understood as cars often require a school for people to even know how to get the thing to run.

Even for simpler applications, just because it's simple doesn't mean people get it if they don't grasp the concept and purpose.

the pace is slow

Every type of help section is slow.

Wading through poor and ignorant customer service is slow.

Wading through help files jumping from features to features just to get an animation in your head of how you can use the application is slow.

Asking around forums, registering and then hoping you don't get flamed is slow.

Even FAQs are slower because these things can skip such basic things as what the application is about when the text description isn't enough. (and assumes you know universal things such as logging in, follow, what not to do to ruin your initial experience, etc.)

I can't jump to the one bit that I am interested in

You can. Annotations/frame buttons/etc.

The point for the user in need is why would they?

There's a reason they want to look at the video and not just half of it. If you mean for further reference or rewinding then that's where the video helps give the user the confidence to understand the help manual better.

Heck even for image manipulation programs I have rarely seen a screencast be more useful than well annotated screenshots...

It could be because you had less problem learning the basics or had someone guide you through it.

For someone like me who doesn't know how to do the most basic of things like cropping, it took a screencast or a video to really help form that image in my head.

No matter how I read the text or see screenshots, I just couldn't get the basics down especially when you combine them into steps.

A screencast affords me an easier way to visualize the real time ramifications of what's happening in front of me and why someone might do something first and then do something next instead of just a bunch of isolated features.

tomos · « **Reply #13 on:** July 09, 2010, 06:36 AM »

First: apologies, I havent read the thread fully

but being a brazen git I'll post anyways

Help:
one challenge is clearly combining (or separating) [1] info about the preferences/options, also possibly the interface/menus etc. and [2] showing people how to actually use the programme.

Interface:
generally intuitive is better - but if you can do something much quicker, in a way that is initially more difficult to learn - I would always opt for the latter.

Screencasts:
I personally think they can only supplement other info (I've seen one major software site where I couldnt see a comprehensive list of features but was allowed to look at very slow moving videos - I gave up)

daddydave · « **Reply #14 on:** July 09, 2010, 07:26 AM »

Interesting conversation -- probably has to do with different learning styles. I was trying to figure out iTunes for a relative's iPod shuffle and I noticed the first thing that appears when you install it is help screencasts, not the program itself. I of course said screw that, and hit Google and dug up lots of outdated information. If I had been in my right mind, I would have checked the help file, but I was too busy thinking that if you can't make a glorified file copy program intuitive, you shouldn't be in the software business.

Anyway there will be a both screencast and a help file for my NANY project, time permitting.

mouser · « **Reply #15 on:** July 09, 2010, 08:04 AM »

iphigenie's points about not searchable is key -- you really cannot meaningfully use a screencast as a good reference manual.

a screencast is fantastic for letting you get a feel for the way the application works and how you might use it, or as a teaching tool, but for advanced users who need to locate some detailed information quickly they are no substitute for a good help manual.

you can also use a a help manual to rapidly familiarize yourself with the range and scope of an application and spot features that are relevant to you in a way that is impossible with screencasts.

i think they are complimentary, especially for advanced applications.

Paul Keith · « **Reply #16 on:** July 09, 2010, 08:46 PM »

you really cannot meaningfully use a screencast as a good reference manual.

Lots of web services use blogs to make screencasts much more easily searchable.

The end point shouldn't be forgotten though: "complimentary" not inferior.

This is the biggest flaw I think with the replies here derailing screencasts.

Even if you try to be neutral, what many of you end up saying is that the traditional help documentation is superior because you can wade through a manual.

Emphasis on "you". Yet help documentation is about help - not help preference.

Even for advanced users, the flaw of many screencasts are that they are dealing with often basic subject matters. This is not so much the fault of screencasts but screencast makers. It is then unfair to say that a help file is superior when what you're basically saying is that an ideal help file is better than majority of screencasts.

Well of course it is. That's like comparing some cream of the crop apples with some rotten oranges. The inherent properties of video though can still apply to advanced topics - it just depends on how you want your advanced topics to be received.

Omitting this virtue is basically tantamount to admitting you don't want to even consider maximizing your help towards your users because you're advanced enough to not need it and you can afford to not go further.

Screencasts are important especially as video annotations improve. Even top professionals of other arts can learn from watching someone work or understand better if they see someone's movements in sequence or frame by frame. Just because text is older than video doesn't mean it's valid to stereotype against the latter. For a long time, people didn't respect or didn't implement images in their manuals and now images are accepted if not encouraged. Video should have this same respect too - especially - especially for helping a user

All help documentations are complimentary towards the application. None of these even texts can survive on their own even if they are easy to search for. We all need some form of clue whether it is the visual trail of the mouse, the keyword associated with search, the clearly written links/outline besides the texts - all these should be here to compliment the help, not give reasons to reduce it.

daddydave · « **Reply #17 on:** July 09, 2010, 09:07 PM »

Even for advanced users, the flaw of many screencasts are that they are dealing with often basic subject matters. This is not so much the fault of screencasts but screencast makers. It is then unfair to say that a help file is superior when what you're basically saying is that an ideal help file is better than majority of screencasts.

Well of course it is. That's like comparing some cream of the crop apples with some rotten oranges. The inherent properties of video though can still apply to advanced topics - it just depends on how you want your advanced topics to be received.
-Paul Keith (July 09, 2010, 08:46 PM)

I can agree with this and was thinking along the same lines. There's a reason people don't RTFM and it's because there are a lot of crappy FMs. And likewise the reason people like me don't watch screencasts unless it is something fairly technical like LINQ or the Python programming language is, there are a lot of crappy screencasts. The question I didn't ask, but worth asking, was "What are best practices for good screencasts?" I do think making a good screencast takes more effort, planning, and rework than making a good help file, so you are very lucky when you find a good screencast, and there are some good ones out there, in particular some of the Microsoft ones. And Microsoft is good about providing transcripts so that they in effect become searchable. I propose a new acronym: WTFSC (watch the fine screencast!)

Paul Keith · « **Reply #18 on:** July 09, 2010, 10:34 PM »

I think transcripts are a great start.

Other flaws I see with screencasts currently is that most of them are on the web and not on a blog page or some other forms that are much more navigational than youtube. (and much more easily downloable)

That said, it's not easy. I think in order to have a fine screencast, just like in order to have a fine manual, a presenter should understand that they are not providing a replacement manual but like with images, they are providing the best help they can provide.

Help is the relative word here.

For most people if a screencast can make it easy for you to both play and not play it and skip to the thing you want, that itself should be a requirement. (Both because it speeds up the loading and because it makes it easy to refer back to a specific section.)

Finally a fine screencast is best used reactive and introductive.

People usually falling in the middle are willing to navigate text rather than video because they themselves probably don't fully know what they are wondering about.

Introduction screencasts are great because it makes it clearer to complete newbies. Reactive screencasts are great because the problem is deemed explainable but too confusing or scary to do step by step.

Example: creating a... troubleshoot help.

If the helper can show you exactly what type of potential screen and errors you may encounter and what moves you need to do, even if you face a different error, it's much less scarier. You're not only able to produce a better text documentation for yourself via jotting down notes but you could better anticipate which section is about to give you the most headache and what you could immediately do to circumvent that trouble instead of a text manual saying If so and so happens do this... If so and so happens do that.

It's also great for long texts that need a form of social proof i.e. ebook making tutorials or web site making tutorials. If someone can immediately warn you to switch to a different app and that this is enough for now and let's not mess with this service because it may hold you back on the next section - it's much easier (and quicker) to grasp where each piece form to achieve a process rather than have a manual say - Don't forget this or Why you should this.

davidqxo · « **Reply #19 on:** July 14, 2010, 10:50 AM »

I liked Steeladept's list in Reply #6.

Much of what passes for Help these days (including screenshots) resembles a useless programming comment that merely echoes what you're already looking at, e.g.,
i++ # increment the index

Two of the most useful help resources I've ever had the pleasure to use are the Permuted Keyword In Context (KWIC) index for the Unix manuals (can someone supply a link for this?) and the online PHP Manual.

Permuted KWIC indexes are SO much more useful than either regular indexes or searching.

daddydave · « **Reply #20 on:** July 14, 2010, 11:16 AM »

Much of what passes for Help these days (including screenshots) resembles a useless programming comment that merely echoes what you're already looking at, e.g.,
i++ # increment the index
-davidqxo (July 14, 2010, 10:50 AM)

Took me a minute to get what you were saying here, but I guess the help file equivalent would be

Edit > Paste

This menu item pastes the contents of the clipboard.

I hate that too. I've seen help files structured that way, and I want to avoid that if possible.