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
Dean Whitlock
Posts: 577
Joined: Thu Sep 01, 2005 5:59 pm
Location: Thetford Center, Vermont USA
Contact:

Unread post by Dean Whitlock »

Hi All,

(And to those posters for whom English is a second language, I bow to your determination and eloquence. Here in the US, very few learn a second language to any degree of fluency, unless they are immigrants or first-generation. Perhaps that is why we are so poor at diplomacy.)

The cost of printed manuals and the difficulty in producing upgrades quickly have indeed driven the species to the brink of extinction. I for one like to have a printed manual available so I can refer directly to the help and the application screen at the same time (without having to switch windows). I will say, however, that I have become a much bigger user and fan of online help since starting to work with H&M a year ago. Part of it was the quality of the H&M online help (thanks, Tim :) ) and part of it was having a bigger and higher resolution monitor. The biggest part was simply having more practice with online help. That doesn't help the auto workers, senior citizens, and others who are unfamiliar with or suspicious of computers in general. There are always cases where a printed manual is necessary.

Online delivery of applications and documentation over the Web has certainly had a major effect on limiting the availability of software on CD and printed manuals. I happen to live in a part of the US where broadband is not generally available to residential sites or is extremely expensive. My home connection is via a dial-up line that seldom achieves the upper limit of the modem. It's very frustrating to download anything over 1 Mb, let alone the tens and twenties of megabytes required to download software. I have resorted to downloading at work and burning to CD there (which can cause compatibility problems, not to mention ethical issues about use of company equipment. I can only hope the situation will improve soon, but the local phone company is not in any hurry to address infrastructure problems in such a rural area.

All this is being a long-winded way to say that, in order to serve all audiences and markets, we should still offer software on CD and printed manuals (or at least a PDF on the CD, or maybe one small enough to download over dial-up). Where I work, we email the PDFs now and send the software via FTP or on CD at no extra charge. We will send a printed manual if requested (though we don't advertise that very loudly :twisted: ). Ours is a limited, vertical market. If we were selling to the general public, I imagine we'd do the whole software-CD-in-box-with-manual package.

One solution to the upgrade problems is to offer change documents (addenda to the manuals) via email or download from the Web site, which my company does. The full manual is updated at the same time but is not shipped to established users unless requested. New users always get the latest version. That works for documenation, but not for software - everyone has to get the entire upgrade or, as Tim points out, they are working with old, potentially problematic software. Every company has to develop its own procedures based on product market, audience, location, etc.

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

Unread post by Tim Green »

Dean,

One thing that totally transforms the way you use online documentation is a dual-monitor setup. I started using them years ago when the first Matrox cards came out -- they were still quite exotic then -- and I've never looked back since. If you do any kind of serious work on a computer you must have at least two monitors, the productivity gains make the cost of the second monitor a negligible expense. I would now refuse to work for anyone who said that I have to get by with only one monitor, it is simply no longer possible for me to get any productive work done on a single-monitor system. (And no, a single wide-screen monitor isn't enough, you need two.)
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 »

Hi Tim,

I would love a second monitor, or even a wide monitor. Unfortunately, I am low man on the totem pole in a small company with a boom-or-bust cash flow in an area with few employment opportunities, within a reasonable commuting distance, for documentors. On the other hand, I love my rural lifestyle :D . Live is full of trade-offs. One adapts.

I wonder if a second monitor would help the computer-anxious people referred to earlier in this thread? Do you think they would be happier with online help if there was a second monitor right next to them all set up to show the help? Or would they still cling to their paper manuals? I suspect that some gentle but firm training with such a setup would get most of them to accept the online help. There will always be a few iconoclasts, of course. One of the problems, IMHO, is that management doesn't invest enough in training on how to use the help effectively. (Alexander excluded, I'm sure :wink: .)

Dean
User avatar
Alexander Halser
EC-Software Support
Posts: 4098
Joined: Mon Jun 24, 2002 7:24 pm
Location: Salzburg, Austria
Contact:

Unread post by Alexander Halser »

I think there's too less demand for a printed manual to ship it physically with every copy. We could use a print-on-demand service to produce and ship individual copies when ordered. However, the H&M user manual is 800+ pages and a POD service for a single item would cost around $100 plus shipping for the book. So, if we offered an additional print manual for $120 including shipping, I doubt that anyone will order it. Self-printing is simply cheaper and more flexible, since you can print the chapter you really want to read rather than all the 800+ pages.
Alexander Halser
Senior Software Architect, EC Software GmbH
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Hi Dean,
Dean Whitlock wrote:I wonder if a second monitor would help the computer-anxious people referred to earlier in this thread?
I think that's very likely. Lack of sufficient monitor space is the single factor that makes using help less efficient because you have to keep juggling back and forth between the application and the help screen. Nobody in their right minds wants to do that -- people try it a couple of times and then give up.

Working in H&M can also get radically easier with two monitors. Then you just undock Topic Options and the TOC and put them on your second monitor and have them available all the time. The same applies to programs like Dreamweaver, or surfing for reference information while you're working.

Does your graphics card at work have a second monitor output? If it does it almost certainly supports dual monitors, unless it's an on-board graphics chip (which is quite likely in penny-pinching work environments).
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: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 ...... 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.
Hi Tim,

No argument with that. But it is then surely odd for EC Software (and many other software companies do the same) to display a "fake" picture of a physical product box on their web site:

http://www.ec-software.com/hm_box1.jpg

If H&M is not actually available in such a box, this is surely misleading to less aware potential customers? In the UK at least, I think it might fall foul of the advertising standards and trade description legislation.

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

Unread post by Tim Green »

Martin,

I can understand this -- I think these "box shots" have become established as a standard practice because software vendors have to show a picture of something, and screenshot of the editing screen or some of the source code isn't really very pretty. Actually, however, boxed versions of H&M do exist, they're just not for sale. They get distributed at conferences and are also used in prize draws and things like that. :?
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 »

Alexander,

Thanks for posting the actual costs of producing/shipping the hard copy manual - that really puts the whole problem in perspective. Many users probably do not print the manual themselves, which also reduces paper use, saving trees, environment, etc. This is counterbalanced somewhat by the fact that those that do print are usually not able to print on both sides, which doubles the number of sheets per copy. And there is a huge side-market in how-to-be-a-dummy books for many of the most common programs (usually because they are so complicated neither the manual or the online help are very useful). Still, I don't think there's any doubt that PDF and online help are the best delivery methods, nor that there will be fewer and fewer companies that offer hard copy as time goes on.

Which brings us back to the issue of employers supporting better training of their employees and providing adequate equipment to help them get their jobs done.

Tim, Thanks for the suggestion about dual monitor outputs. I'm going to check with our hardware guru to see what's possible. I really like the idea of undocking the various panes and having them always in view, particularly when I'm indexing.

Dean
Vladimir
Posts: 48
Joined: Tue Jan 21, 2003 5:21 pm

Unread post by Vladimir »

Let me add my 5 cents:
1. For the information that may be useful but could mess up with direct instructions H&M provides a good solution: expandable sections.
2. I think that electronic help and PDF are for totally different purposes. The first one is for a quick online help when the user wants to know how to do a particular taks or to solve a particular problem, whereas the second one is for thoughtful reading when the user wants to know what and how the software works, and what he/she can get from this software. That requires completely different approaches to these two formats.
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 »

Vladimir,

Very true on both points. Tim, in his original post to this thread, talked about his practice of putting the quick-help how-to info up front, with the more detailed reference information farther down the table of contents and deeper into the child levels. That worked very well for me when learning from the H&M help, and I've tried to follow that scheme when updating my own manuals.

What you say in point 2 indicates a need for much more distinction between the online help and the printed (PDF) help - completely different formats for each. This could probably be achieved in a single project file by putting the deep reference material (the overview, background, philosophy stuff) in topics that only compiled to PDF builds. If you wanted to have it available in the online version but not clutter up the TOC (so as not to intimidate or confuse certain users), you could put that material in invisible topics marked as pop-ups, linking to them only from within the appropriate quick-help, how-to topics. Then you could copy the invisible topics to topics in the TOC that were PDF-only. Or you could embed the invisible topic contents in PDF-only topics. I'm sure there are other possibilities, plus the expandable sections, which will be generally available in the next release (and which I'm looking forward to playing around with).

H&M gives you the possibility of having the overview/background information up front in the PDF version but tucked away in the online version, without having to keep two separate projects in synch. That's pretty darn useful!

Whether or not I'll have time to plan out and implement such a dual-format project is another question. :roll:

Dean
User avatar
Jim Huskey
Posts: 54
Joined: Tue Jan 17, 2006 4:09 pm
Location: Universal City TX
Contact:

Dual Monitors and Printed Manuals Issues

Unread post by Jim Huskey »

Thought I'd chip in here...

DUAL MONITORS:

Dean, did you ever get your dual monitor setup? I've been writing help for one year now only (although I wrote standard operating procedures for multitudes of things in the Navy before retiring), and about four months into the job, I noticed how easy it was for our programmers to get things done - they had two nice LCDs each. I asked for a new video card and ANY two monitors, and was given a nice 15" LCD to go along with a kind-of blurry 17" CRT. It was like turning night into day...I'm sure I became over twice as productive. Eventually they took away the nice LCD and replaced it with a 13" CRT (we're a growing company). This didn't hurt anything except to take up more cubicle space.

For anybody still working on one monitor: you can buy a decent dual output video card for less than $120 and a monitor for less than that. If I'd have known how much better it would be, I would have bought these myself if the company didn't foot the bill.

PRINTED MANUALS

My company produced printed manuals as PDF compiled from Word. They shipped these to customers who requested the manuals only. Still, the cost was very high, since they actually stocked 25+ manuals as a reserve. Since converting the company to H&M and using hyperlinks, we no longer do this. The PDFs are actually very useful for customers to reach and use from Help when they really want the background information.

TAILORING TO CUSTOMERS

Tim, you keep pounding that point, and you are right. My customers are lawyers, paralegals and legal assistants. Most are NOT computer literate, and our software can intimidate them. I spend quite a bit of time telling them the equivalent of "Enter the county in which the estate case will be heard in the County field." These are not people who'd benefit from terms like dialog box, spin box, etc. We do, however, accomodate those who really want to dig into all of our software's possibilities by including manual chapters/help topics on recreating and modifying our products for their local needs.

Final note: I love the software, the support is excellent, Tim is doing a spectacular job with the forum, and I learn important things almost daily from many of the regulars. Thanks and Cheers to All! Jim. :D
Post Reply