TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
-----------------------------
Neumann, Eileen asked:
Currently the practice is to post Word documents on the Intranet......
They have two editing programs (though no licenses for us yet) - Robohelp and Dreamweaver. My question is, which would be best? Also, is there something good that I don't know about in posting Word docs online, vs. HTML? Is Robohelp more useful for creating help files for software programs? What is each program good at?
-----------------------------
So, I'm assuming, then, that you will continue to post information about the application on the intranet? (Small "i" on intranet by the way. You only use the big "I" when you're talking about "the Internet" which is a specific...entity...I suppose. And the Internet is different from the internet. But that's just a pain of a distinction to remember. hehe)
Word docs must go bye-bye. They are foul and evil for all of the reasons already mentioned.
Now, the question is, "Is the intranet the best way to deliver your documnetation?"
Chances are that the answer is no, but that also depends on how your audience will be using your documents. Your readers may prefer something like a pdf file, in which case, post the pdfs for all of the security reasons and version control reasons mentioned on the intranet. That ends the discussion right here. You don't need RoboHelp or Dreamweaver for this.
If your readers want/need information about the application while they're using it, then see if you can work with your developers to create embedded help -- wizards, instructions in the interface, bubble help, blah blah blah. If this is a bust, then your next step is context sensitive help. This should be easy enough for your developers regardless of whether you use RoboHelp or Dreamweaver. I could be wrong on this, but it should be just as easy to point to an HTML file as it is to point to the context-sensitive help file that RH generates.....But then again, I don't know anything about the application you're writing for. We've got a web-based application and so the help button points directly to the correct html page for whatever screen the user is looking at. It's a very simple matter for us.
If you go the html route, keep your docs as your source files, mostly for editing purposes (track changes _can_ be a wonderful thing). You can convert doc to html then use DW to clean up the HTML. You can also go one step further and set DW up to validate your html and to automatically make changes as needed (such as adding closing tags or fixing improperly nested tags). This will help to get rid of even more of Word's HTML wackiness. But as someone else said, at some point, you'll be manually touching up the files.
Now, if you have your heart set on delivering PDFs _and_ some sort of html-based help, then you might want to take a look at OpenOffice.org (it's <fanfare /> free!). You should be able to create a source file, and then convert that to both pdf and html. The html in OOo is pretty clean (I'm not sure about the conversion though), but I'm pretty sure you're stuck with HTML 4.1...4.01....whichever the latest html standard is. (We're using XHTML and so I've sort of been ignoring HTML hehehehe.) Now, I haven't actually tried this in a production environment, I've just fiddled with it at home....so I'm not so sure on the details. Maybe Bruce "Da Open-Source Man" Byfield can jump in and either shoot down this idea or provide further information.
Now, you can also go with html-based help and use one css for formatting your docs for viewing in a Web browser and another css for formatting your docs for print. See CSS Zen to see just how far you can go with a single HTML file and different kinds of CSS files. It really is amazing!!!
Personally, I'd have a talk with the developers, find out if they can and are willing to go the embedded help route....which is the way Microsoft is heading (if that sort of thing has clout). You could go even one step further and provide the kind of help that comes with Visual Studio .NET. Now that is some pretty slick documentation. :-)
Really, all of this comes down to getting answers to some very basic, but important questions, but I can't tell from your post if you've asked and answered those questions.
ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl
WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.
