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.
Subject:Re: online help From:magk -at- mindspring -dot- com To:techwr-l -at- lists -dot- techwr-l -dot- com Date:Fri, 7 May 2010 10:35:45 -0400 (GMT-04:00)
I have used RoboHelp and Flare. I strongly recommend Flare. It works especially well if you need to do single sourcing. (Produce online help and print guides.) Something critical for a sole tech writer: MadCap's fantastic support.
RE: Working with developers.
I produce a context-sensitive help system that ships with the software product. I use Flare to produce a WebHelp system.
1. The developer and I decide on naming conventions for identifiers that link to specific help topics.
2. I create these identifiers in Flare's Alias file and link each to the appropriate help topic.
3. The developer uses these identifiers in the software.
4. Once I complete my work in the Alias file, I compile the help and give it to the developer who includes it in his build and tests it.
5. We do this multiple times as more identifiers and help topics are added.
Other considerations for online help:
1. The help system is a part of the product and needs to be ready when the software is ready. The online help has to meet the same interim deadlines (code freeze, etc.) as the rest of the product.
2. The online help should be checked in using whatever versioning software the developers use.
3. You should compile and check in help regularly so that it is included in routine builds.
4. The help should be tested with the rest of the product. (Even though you tested it before checking it in.) The online help is also a great review source.
Final words (I promise)
Start early and start small when you implement online help. Make sure that you have plenty of time in the release cycle so that the developers aren't distracted by their own projects. (Is it just me, or is documentation always last on everyone's list?)
If possible, start with a smaller product or module.
Use Doc-To-Help's XML-based editor, Microsoft Word, or HTML and
produce desktop, Web, or print deliverables. Just write (or import)
and Doc-To-Help does the rest. Free trial: http://www.doctohelp.com
- Use this space to communicate with TECHWR-L readers -
- Contact admin -at- techwr-l -dot- com for more information -
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
