Help style - being brief and other issues

This forum is for the discussion of the business and craft of writing help. For example writing style, choices of HTML Help or WinHelp or browser-based and so on...

Moderators: Alexander Halser, Tim Green

User avatar
Tim Green
Site Admin
Posts: 23153
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Help style - being brief and other issues

Unread post by Tim Green »

On Concise Help

Over the past couple of months I've been thinking a lot about help writing style. I don't know about you, but in the past I have tended to fall into the trap of writing too much and wasting time and space describing things that are really obvious and self-explanatory.

For example, if we are writing for relatively experienced users (this will depend a lot on the application and its target audience, of course) there is absolutely no reason to describe dialogs that are self-explanatory or include useless menu reference lists telling the users what the Save As... option does. This is like putting a sign saying Tree on every tree in the woods. The programmers put a lot of effort into making things intuitive, and when they succeed I think we can trust that they are intuitive and concentrate on describing procedures. Often it's really enough to say how to open the dialog and what you can do with it.

I also think we need to remember that help is not literature. There is usually no need for long descriptions, and they are often even counterproductive. Users want to know how to use the program quickly, and the best way to give them that is simply Do this, then do this, then do this, finished. Every additional word and sentence means that using the help takes longer and is more difficult.

Separating Instructions and Reference Material

Another thing I've noticed is that mixing up instructions with background information makes help more difficult to use. When we're writing the instructions it's very easy to think about all the things the user needs to know and include them immediately, but that hides the instructions.

How-to instructions are something you return to again and again for reminders, and you want to be able to go through them quickly. You need access to background information but once you've read it you've generally got it and you don't need to refer to it again when you check the instructions.

My new strategy is to keep instructions and reference/background information strictly separate. There are always links to the background info in the instructions and vice-versa, but they are in separate sections. Personally, as a user, I find this kind of structure much easier to use and more practical.

Electronic Help is Primary, PDF Secondary

Keeping instructions and reference separate makes the printed version of a manual a little more difficult to use if you're not going to make a completely different version for the PDF. Without electronic hyperlinks it's just not quite as easy to refer to the Reference section from the How-To section.

I think this is a price that's worth paying, however. Electronic documentation is much better suited to describing software programs than printed manuals. Electronic help has the same non-linear, web-like structure as the software itself, and the strictly linear structure imposed by a printed manual simply cannot match this.

Particularly when I am learning to use a complex program where every function has relationships with other functions, I find electronic documentation much more useful than the printed manual.

Where I do find the printed manual more useful is as a reference work that I refer to once I've learned the program. But when you get to this stage you don't need to follow the links all that often; you are basically just checking instructions for single procedures, or single chapters in the reference section, so there is much less problem with moving between sections. At least, that's my experience.

Any comments or opinions?
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Olivier Beltrami
Posts: 391
Joined: Mon Jul 15, 2002 3:30 pm
Location: Nantes, France
Contact:

Unread post by Olivier Beltrami »

Electronic Help is Primary, PDF Secondary
Extremely on-the-mark and thought-provoking post, particularly the header above. I must admit that I have fallen prey to all the evils you mention, particularly :

1) Stuffing everything I can think of into the documentation (the more the better)
2) Sacrificing some features that would make the CHM or HTML help better, because it would mess-up the PDF.

In a way my excuse for 1) is that my main app is full of a zillion features, most of them very specific to one or two clients only, and usually I use the HM3 file as an instant documentation for me to remember why this feature was added and what the caveats are (as many of these features are addded in a rush because the client wants it now, not beautiful or elegant). My excuse for 2) can also be traced to my clients (how convenient) who are in the print business and for whom the PDF file is a big plus. But do they actually read it ...

I would be interested in seeing an example of a split procedures/background help project. I'm sure I'd find a lot of good ideas to poach :lol:
Olivier Beltrami
https://www.qppstudio.net
Worldwide Public Holidays and Calendar Data
User avatar
Tim Green
Site Admin
Posts: 23153
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Olivier,
Olivier Beltrami wrote:2) Sacrificing some features that would make the CHM or HTML help better, because it would mess-up the PDF.
I think there are many arguments in favor of doing this, including some very good financial arguments. For example, anyone who enjoys doing popups should probably think very hard about them before using them in a project that's also going to appear in PDF, or on the web for that matter. Either you're going to lose the information in the popups or you're going to have to do something structurally very different for the PDF.

Popups may be possible on the web but they have such a bad rap there it's probably best to avoid them anyway.

The same goes for expandable text and all the other cool things you can do with JavaScript -- all a restructuring nightmare for PDF. I've decided to accept the separation of instructions and reference in the PDF but that's as far as I'm going to push my luck. All the other bells and whistles I'm going to leave out. 8)
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
TomHenehan
Posts: 65
Joined: Wed Jul 17, 2002 7:45 pm
Location: New Orleans, LA USA

Unread post by TomHenehan »

Most of my help projects so far have been written for long-established programs originally written in COBOL that have recently been rewritten (with added features, of course) for Windows. The help text in each such case has been the text of earlier print-manual documents, imported into H&M from MSWord and then updated, reorganized, etc., as necessary.

The result is notably longer and more verbose than most Help files I see when running the various software products that I use. I try to edit "down," and also try to divide the text up into numerous small topics with user-friendly formatting (e.g., outline-style indenting).

However, my bosses and I agree that most if not all of the lengthy text needs to STAY IN.

In addition to "how-to" instructions, users need "why" and "when" information. For example, our flagship Vending Management product includes a very large number of different reports. Instructions on how to specify and generate a given report are almost superfluous for all but the newest users ~ the interface is intutitive enough that most users will figure out how to enter the desired specs and click on the "print" or "display" button. Nevertheless, the basic documentation (largely definitions of various data input fields) seemingly needs to be retained ~ because any topic might indeed be the first topic a user looks up.

On the other hand, what users really seem to need are explanations and descriptions of the purpose of each report. For example, if management suspects a given individual of stealing products, we recommend that they generate two reports and compare certain values to each other. If an employee is suspected of skimming money, another report or combination of reports will yield the desired evidence. We try to include this type of information in the most usable form, but I'm not sure that there might not be a better way to structure the help system to provide such hints in the most accessible manner, and without necessarily combining the strategic hints for a given report in the same topic with the nuts-and-bolts "how-to" stuff.

I might add, also, that I do not (yet) use any fancy stuff like popups, etc. ~ mostly because I don't know how, and also because features of this type don't exist in the printed manuals upon which my projects have been based. We do provide PDF versions of all our complete help systems, and also (more importantly) provide PDFs of those subsections (child projects) that describe off-site operation of portable handheld computers. The personnel who will be using these handheld units, obviously, won't have access to Help on PC screens and will need printed manuals.
Tom Henehan
CompuVend, Inc.
Makers of DEX Buzz Box®
3322 Hessmer Avenue, Suite 201
Metairie, LA 70002
User avatar
Tim Green
Site Admin
Posts: 23153
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Tom,

I agree absolutely that the detailed background information is needed. My main point is that it needs to be separated from the instructions because referring to instructions and learning about the background are actually two different activities.

It's not always possible to do this cleanly -- sometimes some background explanation is so necessary that it must be delivered with the instructions -- and when that is the case I do it, I think it would be counterproductive to be inflexible here. But I do think that clarity is improved when you have clear how-to instructions uncluttered by background information, but with clear links to that information so that you can check on it when you need it.

Also, I think how you write will, or should, depend to a great deal on your target audience. If you know that your product is only going to be used by experienced professionals you can take bigger strides and you know that they will be able to execute instructions without you going through every single step. At the same time here too you also have to cater to the "beginning professionals".

Like so many things it's all a lot more complicated than it looks at first glance... :?
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Unread post by Martin Wynne »

Tim Green wrote:referring to instructions and learning about the background
are actually two different activities.
Hi Tim,

I have found that most of the how-to instructions can be conveyed in images,
as numbered call-outs on screenshots. This leaves the words in between for
the more detailed background information. This means that both instructions
and background are in the same place and therefore linked. My experience is
that users soon learn that to find out "how" they should look at the pictures,
to find out "why" they should read the words.

The downside is a lot of large images and a bigger file. How much importance
do you give to file size when planning a project? It seems to me that it could
dictate the overall design more than any factor of style and layout.

Martin.
TomHenehan
Posts: 65
Joined: Wed Jul 17, 2002 7:45 pm
Location: New Orleans, LA USA

Unread post by TomHenehan »

Our users, in general, are not especially computer-literate. Also, there is a degree of employee turnover that may or may not be abnormally large, but which annoys the bejeezis out of our support staff, who resent having to train newbies from square one over the phone.

So, we do probably do need to spell everything out in our Help.

My current approach to integrating background/explanation with nuts-and-bolts "how-to" is similar to how we structured the old print manuals: Each topic describing a given function starts with a text "intro" describing the "how and why" ~ then a screen shot of the window (or first window) being described ~ then the details.

This seems to be fine except in those instances where the "intro" needs to go into finer detail, at greater length, than for the average topic. I prefer for that first screen illustration to be visible (or at least the top of the graphic) when the topic is first brought up. When the first thing that appears is all text (and you have to scroll down before you see that first picture), it seems unnecessarily intimidating.
Tom Henehan
CompuVend, Inc.
Makers of DEX Buzz Box®
3322 Hessmer Avenue, Suite 201
Metairie, LA 70002
User avatar
Tim Green
Site Admin
Posts: 23153
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Martin,
Martin Wynne wrote:I have found that most of the how-to instructions can be conveyed in images, as numbered call-outs on screenshots.
I agree absolutely. Images also make a help file much more accessible and make the user remember things better -- both sides of the brain get activated, and you also have a visual image to link the ideas to, which makes it easier to remember the information. A page broken up with images and white space is also much less intimidating, and the user is much more likely to actually read it.

Unfortunately, producing good how-to images takes time, and when working on a large project I'd price myself out of the market if I used it too much. I'd love to, but a lot of the time financial and time constraints mean I can't use them nearly as much as I'd like to. Particularly in very technical projects designed for professional users, where writing the background information really does involve a lot of work, thought and research.
The downside is a lot of large images and a bigger file. How much importance do you give to file size when planning a project? It seems to me that it could dictate the overall design more than any factor of style and layout.
The importance of file size depends very much on the target market. For consumer shareware applications file size is still very important, a couple of extra MBs can reduce your download numbers quite a lot. But for commercial applications and IT professionals it has become almost irrelevant, within reason of course, because they all have broadband.
Last edited by Tim Green on Wed Feb 02, 2005 7:32 am, edited 1 time in total.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Tim Green
Site Admin
Posts: 23153
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Tom,
TomHenehan wrote:Our users, in general, are not especially computer-literate. Also, there is a degree of employee turnover that may or may not be abnormally large, but which annoys the bejeezis out of our support staff, who resent having to train newbies from square one over the phone.
Have you looked at demo programs like TurboDemo and RoboDemo? Producing good tutorials with them is a lot of work (read: a LOT of work), whatever their marketing blurbs claim. However, if your support staff are having to do a lot of this it might be worth your while to produce a series of tutorials for the newbies to cover the basic training. Then the support staff can simply refer them to the tutorials, which is much better than trying to explain programs over the phone, which is a nightmare.

Last time I looked TurboDemo had an affiliation of some sort with EC Software and H&M users could get it for a radical discount. Not sure if that's still available but it might be worth asking.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Dean Whitlock
Posts: 577
Joined: Thu Sep 01, 2005 5:59 pm
Location: Thetford Center, Vermont USA
Contact:

Unread post by Dean Whitlock »

I have used Camtasia Studio by Tech Smith (www.techsmith.com). I didn't research tools - this one was here when I was hired - however I have been able to turn out some reasonably decent avi-based demos with it. It has screen capture and voice dubbing tools, along with video editing ability and ways to add call-outs and labels. It will also output Flash .swf files and other media, and it's not too expensive. However, I agree with Tim that creating demos is a LOT of work, no matter what tool you use. I would refer you back to his original comments: don't write any more than you need to.

Regarding the instructions/reference duality, I've used several solutions, none of which is perfect. I prefer two manuals, a User manual (basically instructions with a minimum of background) and a Reference manual (everything else). You could structure your online help the same way, with links between them. Managing manuals has proven to be a problem for some clients, however: they want it all in a single book. Others are intimidated by a single, huge manual. (The customers are never wrong, but they are often misinformed!)

The other choice is to lead off with the instruction set, and follow it with the reference material. You could do this either in separate sections (cross referenced), as in the current help for H&M4 (good job, Tim) or sequentially, with the reference material for each command/screen/activity a child topic to the instructions. In either case, the printed manual will have a logical structure.
User avatar
Tim Green
Site Admin
Posts: 23153
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

The other choice is to lead off with the instruction set, and follow it with the reference material. You could do this either in separate sections (cross referenced), as in the current help for H&M4
And of course you always have to break the separation rule sometimes, because there are some situations that are so counter-intuitive that simply understanding the instructions is not possible without some explanation. When this is necessary I always try to keep it to an absolute minimum.

Two other things that are really valuable if you have time for them are pictures and humor (both of which I had much too little time for in the H&M4 help, unfortunately). One thing that I've noticed again and again is that even irrelevant pictures will significantly increase the amount of information that users retain. This is because of the way the human mind works -- we remember information better if we can associate it with an image, and this works best with a funny image. A cartoon that makes you smile will actually work better than an informative screenshot for this, even though you need the screenshot too, of course. In addition to this, pictures break up your pages and make them easier and more pleasant to read.

The same applies for humor. Anything that triggers a positive emotion increases information retention levels. Quite apart from anything else, a manual that makes you smile is simply more pleasant to read. You often have to draw a very fine line, of course -- if you go over the top with this it can be just as counterproductive. But put it this way: When was the last time you were reading the explanatory notes on a tax form and thought, "Wow, I wonder what happens on the next page of this?" 8)
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
C.Trautmann
Posts: 51
Joined: Thu Sep 14, 2006 3:19 pm
Location: Aalen - Germany

Unread post by C.Trautmann »

I needed much time to read, because me english isnt that good...but i have to attack the first header of Tim (Digital first, print second).

I work for a company which is producing engines for automation and the software for whose processes. All used in the automotive industry, from easy workers in germany, poland, hungary,...

They prefer to read from normal paper and be afraid of any computer around them. Its enough for them to handle with the software itself, and now i shall give an electronic guide to them? I only produce that, because the software is searching for a *.hlp file by pushing the help-button. I dont think that somebody will use it this century...

In this case the print manual is much more important than any helpfile, because the users have problems with pc's itself. The printmanual is the only safety for them, i wont help them if i would refer to the *.hlp file.
Also I dont need some references and background informations for this workers...the only need the step-by-step introducing of the software and the solution for their problems. These background informations are only interresting for us, the one who produce the software and install the constructions of mechanical parts, pc's, scanners,...
User avatar
Tim Green
Site Admin
Posts: 23153
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Hi C.Trautmann,

Yes, you have to gear your help to the needs of your users -- if your users are not computer literate or have known computer allergies you naturally have to cater to those needs. But that doesn't change the fact that good electronic help that is properly integrated with the application, making full use of context-sensitive help, is actually more effective than manuals for some things -- provided the users are willing to use it. On the other hand, manuals are definitely better for things like in-depth background study. 8)
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
ASchreyer
Posts: 5
Joined: Mon Apr 11, 2005 2:39 pm

Unread post by ASchreyer »

Hi HELP-WRITERS,

at first, sorry for my english :oops:

But I will also put one's oar in. Firstly I've detected (over the WEB) that Print Manual is legal determinate for selling an software product (in Germany). Secondly a Print Manual is a "figurehead" for the software. Every buyer of the software see at first the packing and the included handbook.

Sometimes I missed it by using H&M (we have downloaded it). I've to work all day long on the screen so it would be very nice to look for help in a print documentation - also it's very well :wink:

I write a help (online and PDF) for a very big application -ERP-software. I like it. But it's very difficult for me to find the best structure of the help because I put it in one project. The biggest problem I have are the lot of levels of the TOC. In our application the dialogs with register contain other dialogs with register and so on... Our programmers should like to have the same structure of the help. In addition its difficult to separate the HOW TO from WHY part! Does anyone have an solution?

I hope I could have given you incitations for significance of an Print Manual.

Annett
User avatar
Tim Green
Site Admin
Posts: 23153
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Hi Annett,

I agree with some of the things you say but the software market is changing very fast and the German legislation (I live in Germany, by the way) is hopelessly out of date as far as this is concerned. Software products change very rapidly nowadays, and the companies that stay with CD distribution are actually much less able to correct problems and provide new features for their users quickly, because they don't want to make their CDs obsolete. There are many software companies that leave serious bugs uncorrected for long periods because of this.

Whilst it is still possible to buy "physical" copies of software products in some cases -- generally for an extra fee -- the Internet is now making this more and more pointless. Even operating systems are generally outdated within at most a couple of months of release.

There are still arguments for owning a Windows CD/DVD, but selling a product like H&M on a CD would only make the product a lot more expensive without bringing any additional benefits for the user. On the contrary -- the user would then be likely to reinstall from the original CD, which would be a disadvantage because it would mean installing an obsolete version of the program. This would lead to trouble for the user and unnecessary support costs as well, because the user would report problems and restrictions that have already been corrected.

The only thing that remains is the need for a printed manual. Even though it is an inefficient way of learning how to use software, many people still do prefer it. At the moment EC Software provides a downloadable PDF that users can print for themselves if they wish, which is a halfway solution. The problem is, producing a printed manual even once is extremely expensive, and since H&M is updated frequently such a manual would have to be re-published several times a year. I'm not sure exactly how much more expensive it would make the product, but it would definitely not be a small amount.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Post Reply