How to write an interactive manual?

Factual Questions
1

I have a possible project at work: write an interactive manual for my work group. We do insurance billing for a major hospital. The current manual is a mish-mash of multi-generational copies of procedures culled from numerous sources. Some are outdated and some are just plain unreadable (all caps is worse when it’s on a 5th-generation copy).

I want to take all these procedures and put them in a nice, tidy CD ROM (preferable) or possibly load it into each person’s PC. I would also have a FAQ, a glossary, and a troubleshooting guide. It wouldn’t need a lot in the way of graphics or animation. Pretty much just text with a few illustrations as needed.

What tools/programs would I need to accomplish this?

2

Probably Powerpoint. You can do some pretty good things with that with not a great deal of effort.

3

Would I be able to have links? Part of the design would include a table of contents and perhaps words and terms from the glossary would be available as hyperlinks.

I guess I would want it to look like a mini-website.

4

Yes, you can. You’d click Insert > Hyperlink and select to link to a pge within this document and fill in the info. It’s a very versatile presentation creation package.

5
      • Just make a web page for each document: write it into a big Word document and export as HTML, and then anybody can view it with a web browser. If all you have are (a number of) simple docs without interlinks (links between different docs) then this is easiest to do. You will need to insert the links by hand, but you’d have to do that with any program you used.
  • If you’re running Win2K there’s an “export light HTML” plug-in you can download from MS that makes the end files much smaller. HTML pages made in regular Word might not display properly in non-MS browsers, however. --For a more browser-neutral result, download OpenOffice or StarOffice and use that to make the HTML pages instead. Their word processors will work pretty much just like MS’s, and export as HTML also.
    ~
6

I say write it in Word, then convert it to PDF.

But light HTML would do, too.

7

Another option is Robohelp . It’s a nice product for doing the sort of thing you want.

Which is ironic, considering the company that makes it used to be called Blue Sky Software.

Basic Word and HTML documents might work fine, depending on the size of the project, but if you want something to do compiled HTML Help documents, like the help files that come with most software, RoboHelp is the way to go.

8

I second RoboHelp. It fits your needs perfectly. As long as you maintain the master document, updating the help file is no sweat.

Second choice is a mini-web site. It would work almost as well.

Forget Powerpoint. It’s a presentation application. While it might contain tools and widgets to create an interactive manual, that is not its intended purpose. Microsoft adds “features” to its applications not to to make each application dynamic and versatile, but solely for marketing purposes.

9

Robohelp costs money, though, and for the beginner, it’s not a tool you can just jump into.

But if you do use RH, avoid Java Help and Win Help, go straight to HTML help. You don’t have to use Word as the HTML editor if you’ve got something else, as well.

10

I second the “forget PowerPoint” idea. It’s good at what it does, but what you’re proposing isn’t really what it does. And in addition to being expensive, RoboHelp tends to do things its own way, which bears no resemblance to the way anything else works, meaning that there is a steep learning curve. There are better solutions for your project, I think.

I’d go for the mini-website. I had great success with this approach a couple of years ago, when I did just what you want to do. It was a 200-page manual, composed in MSWord and converted to HTML using FrontPage. (No, I am not advertising Microsoft products; these were the tools that the client insisted that I use. Of course, you can use whatever tools you like, as long as they get the job done.)

But the mini-website worked very well. This manual was for field service technicians, and they were able to load it on their laptops, and refer to it as necessary using their browser when they were on site. Certainly, they were glad not to have to lug a lot of paper around, and I got a lot of compliments on its ease-of-use.

I’d recommend the mini-website.

11

I also suggest HTML. But do a web-site, not a CD.

A problem you may run into is that different users may have their CD drive mapped differently (D:, E:, etc). This could break all of your links (if served from a CD).

So, the mini-web site would probably work best. An Intranet.

An added bonus of a web-site is that any changes that need to be made only need to be made to the site. THERE WILL BE CHANGES. This way, you won’t have to re-distribute everything. This is huge.

Learning the skills for a site may seem daunting, but HTML is not that hard, and there is tons of free help out there. And just think of the skills you will develop :wink:

12

If you do a mini-website, place all the files in the same directory tree, then make all the internal links between your files relative. That way, once you point your browser to the first file, it knows where to find everything else. Once that’s done, there’s no problem with putting the whole thing on a CD.

A mini-website also has the advantage of being platform-agnostic: with proper design, the client should be able to view the content through any browser (even if older browsers don’t see all of the features). This neatly avoids cross-platform and software compatibility issues (such as might arise when trying to view a Powerpoint presentation on a computer that does not have Powerpoint).

13

also, if you have relative links on a CD, people can’t break the HTML by futzing with it.

But this assumes you have CDs on all machines.

Maybe put the CD on a server and map a drive or shortcut to it for everyone.

14

Not true. You can just link using relative addresses, this way it won’t matter what drive the CD-ROM is mapped to.

15

http://www.helpware.net/

16

I stand corrected. Forgot about that.

17

You’re getting a lot of tool/technology suggestions. Here’s some of the advantages/disadvantages of each, so you can make a good decision.

Website vs. Distributed Document
Question #1 to answer is whether you want to create a website or a document to be distributed. The OP mentioned distributing the document to everyone’s PCs on CDs, which is a fine option, but if your company has an intranet, a website would be an option as well. One benefit is that the manual would be located in one central location, so updating the manual would only require you to update the website – you wouldn’t have to distribute a new set of CDs or worry if somebody is still using an old version. The disadvantage is that you introduce site maintenance/security issues, and that access to the manual requires a connection to the intranet – users can’t view the manual if they’re not on the network or if the network is down.

Note that a website isn’t the only way to make the manual available from a central location. Any document can be placed in a shared folder on a network, and be accessed from any PC with access to the network.

Powerpoint
Powerpoint is presentation software. It can be used to create a manual, but it’s like pounding in nails with a screwdriver – you can do it, but why bother when there are perfectly good hammers lying around? It would also require Powerpoint to be installed on all PC’s that needed to view the document, and that ain’t cheap.

Adobe Acrobat (PDF)
Adobe Acrobat is an industry standard for creating hyperlinked documents and manuals – if you’ve ever lost the product manual for your DVD player and went to the manufacturer’s website to download a replacement, it most likely came as a PDF document. If you’re creating a distributed document, this is a fine choice. Creating a PDF document requires Adobe Acrobat ($300 for standard, $450 for pro), or a document converter that can convert other file formats (such as MS Word) into PDF files. Reading a PDF document requires Acrobat Reader, which can be downloaded free from Adobe. You can even distribute the reader on your CDs, as long as you follow the rules in the license agreement. PDF readers are available for all major operating systems, including PDA’s. Another nice thing about PDF files is they print well if you want to create a hardcopy of your manual – HTML documents require seperate printing of each page and don’t always come out looking like what you expected. Some people do find the Acrobat Reader UI to be a bit clunky.

HTML document
HTML is the standard for interactive, hyperlinked documents. Browsers are available for all operating systems, and everybody’s familiar with the look and feel of an HTML document. Learning to write HTML is very easy, but you can also use many tools to create HTML pages if you don’t want to learn it. Even tools not intended solely for HTML authoring can export to HTML (such as MS Word), although they don’t always produce the cleanest HTML and some (notoriously Word) lean towards Microsoft’s standards rather than more widely accepted standards.

For a website, HTML is your solution. For a distributed document, HTML will work, but you will be distributing a large number of files – a file for each page in your manual, plus each image and any style sheets used. If you’re going to distribute your document, you’re much better off compiling it to…

Compiled HTML Help (CHM)
The current standard for creating a help file in Windows is to compile a collection of HTML files into a single CHM file. Creating a CHM file will be just like creating an HTML document – you write all your HTML files (or have them generated by authoring software), and then use some tool to compile them all into one file, ready for distribution. Because it’s the default Windows help method, no reader is required – any Windows PC already has the software to display it. The help file compiler will have tools for creating a table of contents and index, so you want have to create HTML pages for those, and search capability is built in. This option isn’t much different than creating a PDF, except that the UI is more similar to your web browser, and many people are more comfortable with it. On the other hand, it’s Windows-dependant, and doesn’t print as well. You can download tools for compiling HTML files into a CHM document from Microsoft for free, but that tool (Help Workshop, I think) is kind of clunky. Third party software, such as RoboHelp, can also be used to create CHM files, but then you have to pay.

Hope this info is helpful. :slight_smile:

18

FYI - Microsoft provides a free powerpoint viewer that you can download from their site.

19

But is the PP viewer available for all OSes? If I’m running Mozilla on Linux or Amiga, or I’m blind and am using a screenreader that is reading text to me, or I’m looking at a PDA display, or I’m using Lynx over a slow connection and I’m paying by the kilobyte, or I’m using a WebTV box, PP slides won’t be of much help. A properly-designed web-site yields readable content through all these methods of connection.

20

I’ll have to pass on PowerPoint since I don’t have access to it at work. I do have Word (at home as well) and it has templates for making webpages. I started fiddling around with it today and I think it’ll work for what I need. As far as distribution, it’ll probably be best to put on each PC. That way I can keep all the links the same. I haven’t gotten the OK from my supervisor, but I think she’ll go for it.

Thanks to all for the advice.