The Structure & the Content of Help files
For me help files can be divided into three main sections:
ï Introduction, which includes a general presentation of the application, install / uninstall the application and minimal requirements to use it. It may also include any specific set up and configuration guide.
Some of the information should also be available in the printable Start guide and in the printable Installation guide as the help file is usually installed together with the application itself.
ï The How To section(s), which is the core of the help file and should provide the users will necessary information in order to accomplish specific tasks and activities. This is the most importation section.
ï Contacts & Support, which gives the users the necessary information to get in touch with us and take part of information how to get updates etc.
General guidelines
Keep the language simple and straightforward. The UI of the application is what the users usually see and therefore there is no need to add technical details that the users never will take part of, i e avoid information overload.
(No, most users are not interested to learn how amazing UDFs or procedures weíve been creating to solve specific issues withÖ)
If the application explicit target beginners then itís highly recommended to either avoid the use of abbreviations or explain them. The same is valid for all the buzzwords that tend to be in use but never explained (Iím no exceptionÖ).
However, it does not necessarily mean that all the explanations should always be on a basic level. A good judgment should guide us to decide the level of complexity together with information about the target group of the application.
Use screenshots as they give the users a quicker and better understanding where to do the activities in the application.
Avoid using too many hyperlinks and too many popup. If You believe You need many hyperlinks and/or popup then You probably will need to completely re-design the structure.
Check the spelling in the help file. Personally I can get irritated if common words are misspelled and beside that the impression of a professional applications increase if misspelling is avoided.
In my experience itís a good situation, if possible, to let a member of the target group help out with the creation of the help file. An even better case is if a professional documenter does do the work but so far I have not yet have had that possibility. For smaller projects itís not reasonable from a strictly financial point of view.
A helpfile should include the following tabs:
ï Content
ï Index
ï Search
Both the Index- and Seach-tool may seem to be overkilling but some users actually use them instead of drilling down via the Content-tab. Except for that I would say that the existence of the tools reflect the present standard for help files.
The following screenshot shows an example of the basic structure and the content of a help file:
(Yes, the names of the tabs etc in the above image are in Swedish).
It may seem to be a simple task to create help files but in my experience it takes a while and lots of practice before we can create help files of good quality.
The process of creating helpfiles gives us valuable input on how the applicationís UI is structured and it can also help us to detect any major flaws in the UI.
Over the years a practical standard seems to be developed for how help files should be set up but as far as I know little has been written about it. Hopefully some of the above will give You some ideas about it.
In the next post I will discuss how to create help files with a help authoring tool (no, itís not with Excel ;) ).
Kind regards,
Dennis
Ya. Ve have dem in Sveeden too… You here that in Minnesota a lot. ;-)
doco,
It’s amazing that Swedish still exist to some extend in You area. After all, it’s more then 100 years go the big immigration from Sweden took place.
How common is Swedish lastnames like Olsson, and Johansson?
Kind regards,
Dennis
In Sweden at least, the something-“sson” names are very common. They actually come from they you in the old days where named after your father, like they still do in Island. My first name is Melker so my son would there for have the surname Melkersson.
Some statistics for you, the top 20 of people in Sweden named:
1 Johansson 279 858
2 Andersson 276 865
3 Karlsson 214 378
4 Nilsson 186 947
5 Eriksson 148 880
6 Larsson 134 660
7 Olsson 119 771
8 Persson 116 901
9 Svensson 112 577
10 Gustafsson 77 559
11 Pettersson 70 990
12 Jonsson 61 776
13 Jansson 53 809
14 Hansson 46 877
15 Bengtsson 36 617
16 Jnsson 35 862
17 Petersson 32 892
18 Carlsson 29 929
19 Magnusson 27 743
20 Gustavsson 27 514
Population: 9 029 002 as of July 2005
Uh, back to the question of help files.
I’ve decided to go the route of HTML files for help on the large Excel project I’m working on. The benefit of this for me is that I don’t have to create them. A co-worker (author) can create help in Word, Powerpoint, Excel, whatever, and save it as HTML. It can have unlimited formatting, screenshots, video, audio – you name it. He doesn’t have to know anything about HTML to do this.
Because my client is on a worldwide intranet (BIG company), all users should be able to access the help online. If they work offline often, we will encourage them to copy the HTML files to a local directory. If my Excel app can’t find the HTML files online, it will look locally (I’m still trying to figure that part out).
I put a hidden sheet in my workbook where the author can list all of the HTML file names. Each of them corresponds to a userform in the workbook. At the corner of each userform, there is a “?” box which calls up a form with a WebBrowser control.
It’s really slick and the client is impressed.
OK, so here’s a question about the browser control:
How can I tell if the WebBrowser control cannot find the URL I’ve passed it? I’ve looked at all of the properties and nothing looks promising. At one point, the LocationName property said, “Cannot find server”. But that’s not always true.
Public Sub ShowHelpHTML(URL As String)
WebBrowser1.Navigate2 URL
Do
DoEvents
Loop Until WebBrowser1.ReadyState = READYSTATE_COMPLETE
If WebBrowser1.LocationName = “Cannot find server” Then ‘this doesn’t always work
‘code here to look for local files…
End If
End Sub
Alternatively, is there a way outside of the WebBrowser control to tell if a URL points to a real website?
Thanks,
Dave
Nevermind, I found it.
The WebBrowser control fires a NavigateError event if the URL isn’t found.
Thanks anyway,
Dave
Dave,
Check out the Web Help we can create with RoboHelp.
I use it for several solutions and it’s even more easier then Your present approach.
The price for it should be acceptabel for Your BIG company :)
Kind regards,
Dennis
Hi Dennis,
What an outstanding article… Bravo.
Dennis, what would be your top recommendation for a Help writer that was not so expensive as RoboHelp? RoboHelp looks really nice, but at US$1000+ it really is exensive…
Very nice layout in your simple example in your article, btw.
Keep up the great work :-),
Mike
CM Mike,
Thanks for Your kind words :)
RoboHelp and Doc-To-Help are the two tools that sets the standard but as You point out they are not cheap.
However, I’m a RoboHelp addict so I’m not the right person to try to answer Your question but here are some URL:s of general interest:
Microsoft HTML Help (Free and simple) :
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vsconhh1start.asp
HelpMaster (Pointers to many tools with different price levels):
http://www.helpmaster.com/index.htm
For technical stuff, i e working with Helpfiles in VB/VBA:
David Liske’s excellent site:
http://www.mvps.org/htmlhelpcenter
Ivan F Moala’s
http://xcelfiles.homestead.com/Index.html
And perhaps some coming post here from me ;)
Take care,
CM Dennis
Another option is Author-IT which can output into help files and Word docs (among others). Single user licences are cheaper than RoboHelp IIRC. It’s listed as one of the standalone tools on the HelpMaster site. We’ve started experimenting with it and it looks good so far. See http://www.author-it.com for more details.
I’m a regular reader of dicks-blog, lots of good ideas found so far. Regarding Denis theme, which is offered in several parts, I would appreciate to find a link to the previous part.
This of course is a proposal for all themes going over several parts.
And Dennis, I’m very interested in your thread. Thanks. I know, it’s not easy – I myself made first steps creating chm-files.
Regards,
Beate
Beate,
I finally managed to locate it :)
http://www.dicks-blog.com/archives/2005/09/19/the-need-for-documentation-part-i/
Yes, I will make sure to always add a link to previous part of my theme-post.
Kind regards,
Dennis