Technical writing tools

MarcomTeam Page 1
Technical
Writing
Tools
www.marcomteam.org

MarcomTeam Page 2
Introduction to Technical Writing Tools
Contents
RoboHelp ............................................................................................................................................2
AdobeFrameMaker.............................................................................................................................5
MadCap Flare......................................................................................................................................8
Author - IT.........................................................................................................................................12
Epic Editor.........................................................................................................................................14
Using Doc To Help.............................................................................................................................16
ForeHelp............................................................................................................................................20
Adobe Captivate................................................................................................................................25
RoboHelp
Introduction
RoboHelp X5 is an authoring tool sold Adobe Company. RoboHelp was
previously product f rom eHelp Corporation (formerly Blue Sky Software).
In an easy "WYSIWYG" format, it allows you to organize information and
create pathways and interactive links so a user can find desired or
necessary information (and the user can do so in a non- linear intuitive
way that is helpful to learning).
You can add images (photos, drawings, images, video) and audio to your
topics to support your content and enhance your online information. You
can even use these images as links(hotspots) to other topics. In a topic,
images are part of the text that makeup atopic and they flow with the
text as you add and delete information. You insert images into your topics
in the RoboHELP WYSIWYG Editor.
RoboHelp also lets you create pop-up text hotspots and a Table of
Contents, Glossary, and Index as you develop text. When development is
finished, depending on the version of RoboHelp you have, you can provide
different output formats (print, Microsoft HTML, JavaHelp, etc).
RoboHELPOfficeX5 Structure displays:

MarcomTeam Page 3
Basic Steps followed for creating a help file:
• Select an authoring environment.
• Create aHelp project.
• Create topics.
• Link the topics.
• Create a table of contents.
• Create an index.
• Compile the Help system.
• Test the Help system.
• Deliver the Help system.
RoboWinHelp
RoboHELP WinHelp is a robust Help authoring tool that allows us to create
a sophisticated Help systems. We focus on design and content while
RoboHELP handles the complexities of creating Help systems for us
behind the scenes.
RoboHELPWinHelp includes the following Features:
• Working Area: Microsoft Word
• Project FileExtension: (.hpj)
• Output FileExtension: (.hlp)
• Each topic is differentiated by a pagebreak in a single document.
• Document FileExtension: (.doc) is for default working area and (.rtf) is
were a backup copy is been created.

MarcomTeam Page 4
RoboHELP Explorer
RoboHELP Explorer displays an integrated graphical view of the Help
project and all its elements, so that it is easy to see and organize the
whole Help project at once – not just one element at a time. RoboHELP
Explorer contains the Project Manager (Project tab), the TOC Composer
(TOC tab), the Index Designer (Index tab), the Tools tab,
imageWorkshop, Link View, and Topic List. It has the Right and Left Panel
were the Left Panel displays the Project Tab, TOC Composer, Index
Designer, and Tools Tab and the Right panel displays the Image
Workshop, Link View, and Topics.
Project Manager
The Project Manager provides an entry point for viewing and working with
all the elements of the Help project. It displays an expandable/collapsible
hierarchy of folders that organize topics, broken links, Map IDs, windows,
images, and other project files into manageable groups.
RoboHELP HTML
RoboHELP HTML is the only specialized WYSIWYG (What You See Is What
You Get) authoring tool for creating Microsoft HTML Help for Windows.
Additionally, it is ideally suited for developing cross-platform, browser-
independent Help (WebHelp) and JavaHelp.
RoboHELP HTML includes the following Features:
• Working Area: Microsoft Front page
• Project FileExtension: (.xpj)
• Output FileExtension: (.chm)
• Each topic is aNew HTML File
• Document FileExtension: (.html)

MarcomTeam Page 5
RoboHELP HTML provides advanced Help authoring solutions, including
the ability to create powerful Microsoft HTML Help and other major Help
formats in one easy-to-use environment. RoboHELP HTML offers superior
Help navigation, search, and project management features.
Here are some of the intuitive features you can take advantage of in
RoboHELP HTML:
Manage your project easily
• Quickly view a hierarchy of files and folders and organize topics,
images, stylesheets, and other project files into manageable groups.
• Track topic development and quickly view a list of topics or their
properties and organize them by attributes.
• View the structure of your project graphically using Link View. It works
like a navigation map, displaying all hyperlinks among topics and "red
flags" broken links so you can quickly isolate and fix them.
• Use reports to track the progress of your project. You can customize
reports to suit your needs and view them online or from printed copies.
Design custom tables of contents
• Construct a table of contents by dragging and dropping topics right into
the TOC Composer, or let it generate a TOC automatically for you.
Rearrange topic order, create a multilevel hierarchy, and see results as
you create them.
• Organize topics with an expandable/collapsible TOC. From a Contents
tab, users open books to find pages and they click pages to view their
associated topics.
Create indexes quickly
• Build a keyword list right in the Index Designer. Drag and drop topics
into it and create a multi-level, sorted index.
• Test and edit your index just by looking at your keywords and their
associated topics.
• Take advantage of automated indexing with the Smart Index Wizard. It
searches the content of your topics and suggests keywords and keyword
phrases. Use it to quickly create an index from concept to finish and to
add suggested keywords to individual topics.
AdobeFrameMaker
Introduction
FrameMaker is a complete publishing system. It's a word processor, page
designer, graphics editor, and book builder rolled into one package. You

MarcomTeam Page 6
can use this versatile application to write simple one-page memos or to
produce complex multi chapter documents with imported graphics.
FrameMaker is a document creation package, suitable for UNIX, Windows
& Macintosh operating system. This versatile package acts as an engine to
unveil documents in HTML and PDF File formats.
What we can do with FrameMaker?
Text Flows
• Creating aNew Document
• Creating Parallel Text Flows
• Adding Text Frames
• Adding Disconnected Pages
• Connecting Text Frames
• Tracking Text Flows
Conditional Text
• Creating Conditional Text Tags
• Applying Conditional Text Tags
• Showing Conditional Text
Controlling Conditional Text at theBook Level
• Turning Conditional IndicatorsOff at theFileLevel
• Turning Condition IndicatorsOff at theBook Level
• Removing aCondition
• Selectively Removing aConditional Text Tag
• Finding Conditional Text
• Importing Conditional Text Tags
• Deleting Conditional Text Tags
Variables
• Creating User Variables
• Inserting User Variables
• Modifying User Variables
• Adding Character Formats to User Variables
• Converting User Variables to Text (Deleting User Variables)
• Inserting TableSystemVariables
• Drawing aRunning Header or Footer Background Text Frame
• Adding aRunning Header/Footer Variableto theHeader Box
• Adding aHeader Box to theRight Master Page
• Adding aTab to theRunning Header/Footer Variable
• Adding theCurrent Pageand PageCount Variables
• Modifying theCurrent Page# Variable to IncludeaPrefix
• Changing thePageNumber Format at theFile Level
• Importing Variables

MarcomTeam Page 7
Cross-References
• Inserting an Internal Cross-Reference
• Inserting an External Cross-Reference
• Jumping to theSource of aCross-Reference
• Creating Cross-ReferenceFormats
• Adding Character Formats to Cross-References
• Updating Cross-References fromtheBook Window
• Updating Cross-References fromWithin aFile
• Resolving Cross-References fromtheBook Error Log
• Resolving Cross-References fromtheUpdateUnresolved Cross-
ReferencesDialog
• Importing Cross-ReferenceFormats toOther Files
• Deleting Cross-ReferenceFormats
• Converting Cross-References to Text
• Using theFind/ChangeDialog to Find Cross-References
• Generating Lists of External and Unresolved Cross-References
Text Insets
• Importing BoilerplateText
• Changing aText Inset'sProperties
• Updating Text Insets fromtheUpdateReferencesDialog
• Updating Text Insets fromtheText Inset PropertiesDialog
• Opening aText Inset FromWithin aFile
• Converting Text Insets to EditableText
• Using theFind/ChangeDialog to Search for Text Insets
Hyper text
• Creating aNamed Destination
• Creating an ActiveArea for aHypertext Link
• Creating aJump to theNamed Destination
• Testing aHypertext Link
• Viewing an Existing Alert Message
• Creating and Viewing an Alert Message
• Viewing Named DestinationMarkers
• Testing Hypertext Markers
• Adding Navigational Buttons toMaster Pages
• Using theFind/ChangeDialog to Search for Hypertext Markers
Generating Books
• Generating and Saving aBook
• Adding Files fromtheBook Window and AddMenu
• Adding FilesUsing Drag and Drop
• Copying and Pasting Files fromOneBook to Another
• Adding Non-FrameMaker Files to theBook
• Selecting Files in theBook Window
• Rearranging Files in theBook Window

MarcomTeam Page 8
• Deleting FilesfromtheBook
• Numbering FilesConsecutively
• Restarting theParagraph Numbering in Each File
• Setting Up FootnoteNumbering
• Updating Books
• Troubleshooting Booksby Importing Formats
Tables of Contents
• Creating aStandaloneTable of Contents
• Creating aTableof Contents from theBook Window
• Viewing theBody Pages of aTable of Contents
• Jumping to theSource of aTableof ContentsEntry
• Viewing andModifying theBuilding Blocks on theTOCReferencePage
• Adding Prefixes to PageNumbers in the Table of Contents
• Adding a Right Tab and Leader Dots to the TOC ReferencePage
• Formatting theParagraph Formats in the Table of Contents
• Changing the Set Up of a Table of Contents
• Basing a New Table of Contents on an Existing Template
• Updating the Formats of an Existing Table of Contents
• Updating a Table of Contents
Indexes
• Indexing aWord to theRight of theIndex Marker
• Creating Index Entries by Typing Index Text in the Marker Dialog
• Adding Character Formats to Index Entries
• Suppressing thePageNumbers for Index Entries
• Creating PageRanges in Index Entries
• Specifying the Sort Order for Index Entries
MadCap Flare
Unlike WebWorks Publisher, which is essentially a sophisticated filter for
single-sourced content, Flare is a true help authoring tool. You can create
help projects in Flare without any other tools or documents. You can
import RoboHelp projects (but not Webworks projects), or Word,
FrameMaker, or HTML files. You can also use Flare as a single sourcing
tool, writing in Word or FrameMaker and reimporting your content into
Flare when you make changes. Flare is more limited than WebWorks in its
output options, which are HTML Help, WebHelp (a browser-based format),
DotNetHelp (a MadCap-developed format designed to work with Visual
Studio 2005 applications), HTML and PDF.
Flare's interface is similar to RoboHelp's and to a lesser degree,
WebWorks ePublisher's. At the top of the window, there are the usual

MarcomTeam Page 9
menus and toolbars. In a left pane, there are tree views of either your
content or your project's resources. In the right pane, you can display
your content or the resources you're working with. At first, I found the
interface a bit daunting and somewhat gaudy, being used to the rather
more spartan interface of WebWorks ePublisher, but it didn't take long to
learn it. Toolbars and menus are fully customizable as well. Given the
complexity of the Flare interface, and the number of topics and resources
you can have open at once, a second monitor would be a wise
investment.
Flare uses Cascading Style Sheets to control its formatting. If you're
familiar with CSS, you'll have no problems controlling or changing formats
in Flare. Using CSS classes makes it easy to control the format of text
across an entire project. You can also apply formatting overrides or use
direct formatting and ignore the CSS styles completely. Flare also lets you
group styles into style sheets, which you can apply to either topics or
tables to help maintain a consistent appearance.
Like FrameMaker, Flare allows you to create master pages, which you can
apply to topics in both the online and printed output. If you're using them
in printed output, this is where you would add page numbers, headers,
and footers. Master pages can also contain breadcrumb links and mini-
TOCs for groups of topics.
For more control over formatting, you can apply skins, which can
completely change the appearance of a project. Flare's skin editor allows
you to control the size and location of the help window, which buttons
appear in the toolbar, the format of the tabs, style of the TOC and index,
and many other items. I much preferred Flare's approach to skins to that
of WebWorks ePublisher, which offers more skins out of the box, but
requires manual editing of files and graphics to change many of the skin
elements. You can preview your changes, and although the preview uses
a sample project instead of your own, it's still a real time saver.
Benefits:
With Flare, you have a complete authoring and publishing system with full
support for maximum content re-use (single-sourcing) and you can
publish to online, desktop, and print formats (multi-channel publishing):
 Topic-based content development
 Content reuse with conditional text, variables, snippets, outlines,
and more
 Flexibility with XML and CSS
You can easily create:

MarcomTeam Page 10
 Policy and procedure manuals
 Knowledge bases
 Software documentation including online help with context
sensitivity
 Reference books, manuals, or illustrated guides
 Hardware or maintenance manuals
 And more
Flare integrates with all MadCap products so you can extend the power of
Flare as your needs grow.
 MadCap Feedback server provides reports on customer usage of
your documents
 Mimic, Capture, and Echo provide multimedia publishing integration
 MadCap Lingo enables localization
 Analyzer scans your project for suggestions to improve your project
efficiency and consistency, and adds speed to your authoring
 Contribute content using X-Edit Contribute and/or insert comments
using X-Edit Review
You just won't believe how easy your life can be. Imagine, the power and
flexibility of content management but at prices anyone can afford. You
choose the specific modules that you need and will actually use. Why
didn't someone think of this sooner
Features:
Madcap Flare includes all the features you expect in a high-end XML-
based publishing system, including:
 Single-sourcing to multiple outputs including straight to the printer,
Microsoft® XPS, PDF, Adobe® FrameMaker®, Microsoft® Word™,
cross-browser and cross-platform formats for use over networks or
the Web, and formats for the Microsoft® Windows desktop
(Microsoft® HTML Help and our popular DotNet Help)
 Conditional text to create multiple versions of your content from
one source
 Variables and snippets specify pre-set terms (variables) and pre-set
chunks of formatted content (snippets) from a library of reusable
elements
 Cross-references that become hyperlinks online and page number
references in print
 Auto-numbering for volumes, sections, paragraphs, and pages
 Complex page layouts including graphics, headers, footers, and
multiple columns

MarcomTeam Page 11
 Unicode support to author in any left-to-right language, including
French, German, Italian, Spanish, Swedish, and more
 Multiple document Outlines provide as many outputs as you need
 Global Project Linking ? share and update common elements across
multiple projects
Import Existing Content
 Adobe® FrameMaker® (.fm, .mif, .book)
 Microsoft® Word™
 HTML/XHTML
 RoboHelp® projects
 HTML Help projects
Generate Multiple Outputs
 Cross-browser, cross-platform Help (WebHelp or WebHelp Plus)
 Microsoft® HTML Help (.chm)
 Help for .NET applications or Windows® Vista (DotNet Help)
 Adobe® FrameMaker® (.fm, .mif, .book)
 Direct PDF
 Microsoft® Word™ (.xml, .doc)
 Direct XPS and DOCX
 WebHelp AIR (Direct Adobe® AIR integration)
Multi-Language Support
 Fully Unicode enabled
 Double-byte and Asian language support
 Language support for Eastern European languages
 Seamless integration with MadCap Lingo for easy localization
Single-Sourcing Features
 Generate multiple targets from one project
 Variables (re-usable text and content)
 Conditional text (at all levels)
 Style sheets for topics and tables
 Easily synchronize with Word™ or FrameMaker® documents
Ease of Use
 Auto-numbering
 Visual document structure display
 View and edit multiple docs simultaneously
 Command line compiling
 Drag-and-drop table columns and rows
 View, filter, and access all files from a single list

MarcomTeam Page 12
Source Control Integration
 Direct integration with Microsoft® Visual Source Safe and
Microsoft® Team Foundation Server
 Integration with industry source control systems that use the MS
SCC API interface
 Faster server-side search
 Searching of non-XHTML content (Word™ documents, PDF files,
etc.)
 Automatic runtime merging of projects without any in-project work
Author - IT
Author-it (formerly AuthorIT) is a Content Management System which is
intended to be used by anyone responsible for creating, maintaining, and
distributing content. The foundation of Author-it resides in its ability
to single-source content, thereby eliminating redundancy and
streamlining content. While Author-it is often referred to as a help
authoring tool, its underlying approach to single sourcing can be applied
to any industry.
Author-it is a program that you use to author, manage, and publish
documents in a variety of output formats, all from a single-source
database.This means you can change the document in one place, and
your changes will be contained in each output format when you next
publish them.
Author-it uses Publishing Profiles to determine several things, including:
 which outputs a book can be published to
 which users can publish using that profile
 the release states content must be in for it to be included
These profiles are fully customizable, and you can create as many
additional profiles as you need to suit your requirements and your
deliverables. More details on Publishing Profiles can be found in the Using
Author-it Guide.
The available output formats Author-it can publish to are:
 Printed Word document
 PDF document
 Windows Help system
 Pure cross-platform HTML pages with integrated navigation tree
 XHTML transitional pages with integrated navigation tree

MarcomTeam Page 13
 HTML Help system
 Java Help system
 Oracle Help for Java system
 DITA (Darwin Information Typing Architecture)
 Author-it XML
 Author-it Website Manager
Each output format has different constraints and considerations.
Author-it stores all information as objects in a central database, giving
authors the ability to combine and reuse objects in various ways. Object
types include:
 books
 topics
 file objects
 hyperlinks
 styles
 glossaries
 tables of contents
 indexes
 publishing profiles
Because content consists of independent objects, multiple authors can
work in the central database (called a library) at the same time.
In Version 5.2, Author-it introduced a structured authoring solution. The
company says that by separating data persistence, where the data is
stored or saved, from the business logic, where individual business rules
are defined, organizations can now implement structured authoring in a
controlled manner.
The Author-it Base User module includes importing, authoring, and
publishing capability. Further modules that can be licensed include:
 Offline Authoring
 Project Manager
 Localisation Manager
 MIF Import Filter
 Web based Editor
 Integration Server
 Xtend Authoring Memory

MarcomTeam Page 14
Epic Editor
Epic Editor is a robust, reliable native XML authoring tool. Provides the
same kind of WYSIWYG editing functionality, but works with XML
documents directly. With no import/export process to foul up the works,
and an environment designed from the ground up to allow writers to
generate valid XML documents, Epic Editor really sets a standard to which
Framemaker can only aspire.
Epic Editor's interface looks a lot like your average word processor, the
most obvious exception being the Document Map on the left-hand side of
the window. The Document Map displays a structural view of the tags,
attributes, and content of your document. By default, it scrolls in sync
with the main editor view, so you can always see at a glance the structure
of the particular document area you're working on. You can even edit
your document right in the Document Map. And for the less technical
user, the Document Map can be hidden entirely.
Epic Editor has integrations with Documentum, Oracle, FileNET and
Interwoven.
Features:
 Change tracking. Provides groups of authors the ability to track
text and markup changes made to a document. Epic Editor's change
tracking capability fully supports the process of information
creation, review and approval so that groups of authors and editors
can work collaboratively to provide customers with fresh, consistent
and complete information on all types of media.
 Publishing standards support. With Epic 4.2, Arbortext now
provides the industry's most powerful support for the Extensible
Stylesheet Language (XSL), through its embedded XSLT processing
engine and XSL-FO processing engine. Because XSLT enables online
publishing and XSL-FO enables print publishing, organizations that
implement Epic 4.2 can build an automated multichannel publishing
system.
 Inline editing of compound documents. Enables authors to edit
document components directly within the same window instead of
launching separate windows. When an author tries to change a
component, Epic automatically checks it out or protects it from
changes, based on an inquiry to the repository.

MarcomTeam Page 15
 Format conversion. Epic's enhanced mapping function reduces
development time by 75% for setting up conversions from other
publishing sources to XML (and from XML to those sources).
 Content management. Version 4.2 continues Epic's tight
integration with many content management systems with upgrades
to support the latest releases of Documentum (version 4.2) and
Oracle iFS (version 1.1.9).
 Programming standards support. Through Epic's new support
for JavaScript, existing bindings to Java, C/C++ and COM, and
enhanced support for the W3C's Document Object Model (DOM)
API, developers can create customizations using their preferred
programming languages. Epic supports DOM Ranges and Level 2
events.
 CJK support. Epic 4.2 provides editing support for Traditional
Chinese, Simplified Chinese, Korean and Japanese content.
 LinkSetting. Simple and efficient setting of links and hotspots by
the LinkCompositor.
 Template management. Support of any template which can be
implemented in the document at any time.
 Illustrations. When an illustration is inserted from the CMS,
automatically the necessary entities for this are exported from the
CMS and declared in the document.
Editing
The Document Map is a tree-style graphical view of your SGML/XML
document that clearly depicts the structure of your document. The editor
will only allow you to create well-formed XML, inserting necessary
elements as you go.
The most powerful features are available when you have a DTD defined
for the document as the entire document is parsed and validated in real
time. When you reach the end of an element and hit ENTER, the Quick
Tag feature displays a popup menu containing only valid elements
according to the DTD. This also applies to cut-and-paste or drag-and-drop
operations. After selecting an element, you can drag it to another location
in the document. Epic Editor visually indicates if it's possible to insert the
element at the given location according to the rules defined in the DTD.
Sometimes an insertion is possible only with the inclusion of another tag,
which Epic Editor indicates and then does the work for you. This makes it
a breeze to create documents that are compliant with either an industry
standard or custom DTD.
While editing your structured content via the Document Map is easy to do,
it's even easier to edit in the rendered view. The rendered view window
displays your content after applying a stylesheet, giving you a real-time
preview of your final output. Making changes in this view is as simple as

MarcomTeam Page 16
using a word processor and all changes are immediately visible within the
Document Map.
Collaborating
While Epic Editor works well as a stand-alone editing tool, it excels at
facilitating collaboration. Content can be searched, checked in, and
checked out from a repository without ever leaving Epic Editor.
Additionally, for some repositories Epic Editor can automatically break
apart structured documents into their elements for storage.
Abortext has chosen to support a best-of-breed repository approach.
Currently, the product includes an adapter for connecting to Documentum
4i. An adapter for integration with Oracle iFS is also available as an add-
on.
Epic Editor 4.2 now includes a Change Tracking feature, which allows an
author to view all the individual modifications and revisions that have
been made to a document. This new feature facilitates information
management processes such as content creation, review, and approval.
Extending
The Epic Editor exposes a robust API consisting of over 500 functions and
75 events for developers to extend and customize the product to their
needs. Supported programming languages include C, C++, Java,
JavaScript, Visual Basic, TCL, Perl, and Python as well as a COM interface.
Additionally, Abortext has included its custom scripting language,
Abortext Command Language (ACL). With ACL you're also able to execute
individual commands from within Epic Editor using a simple but effective
command-line window.
Using Doc To Help
Creating Content
Since Doc-To-Help uses Microsoft Word as its topic editor, creating
content is basically a matter of typing text, creating tables, and inserting
pictures in the same way as you would for a regular Word document. You
have the benefit of using a familiar authoring environment, and you can
take advantage of some of Word's advanced productivity features, such
as macros.
The disadvantage is that the Word editing environment was not designed
specifically for Help authoring. As a result, a number of features built into
Word are totally redundant within the Doc-To-Help environment. Also,
you do not have built-in authoring support for some of the more advanced
features of a Help system, such as DHTML expanding text and drop-
downs. You can achieve these effects, but only by typing the required

MarcomTeam Page 17
HTML code into your document, and then using the Doc-To-Help toolbar
to mark it up as "HTML passthrough code". This is something that many
Help authors would not feel comfortable doing.
Applying Formatting and Styles
Each of your Help targets (that is, the output formats that you generate
from your project) has a corresponding Word document template. This
document template must contain a set of paragraph and character styles
whose names match the styles that you are working with in your source
Word document. These style definitions within each Word document
template determine the text formatting within the corresponding Help
target. So for example, what Doc-To-Help actually does when you
generate an HTML-based target is to create a Cascading Style Sheet (CSS
file) based on the styles within the appropriate Word document template.
The advantage of this approach is that you don't need to know anything
about CSS, and can instead use Word's familiar style-editing features for
creating the desired formats with the document template. The downside
for more savvy authors is that Doc-To-Help does not write HTML and CSS
in the way that you would necessarily choose to do if you had full control.
For example, it marks up all paragraphs (including headings) using the
<P> tag, and differentiates between the original Word paragraph styles
using Classes. This conflicts with accessibility guidelines from the Word
Wide Web Consortium (W3C), and means that the resulting HTML lacks
the heading tags (H1, H2, etc.) that some specialist browsers rely on to
recognize page structure.
Creating Links
Many different ways are available to create hyperlinks between topics,
using either Microsoft Word or the Project Editor. Adding a topic link
within Word is not as easy as it might be, because there is no way to
insert the link text automatically. This is not a problem if you are adding
an inline link within a paragraph that you have already typed, but it is a
little annoying if you are creating the link from scratch.
Doc-To-Help will convert cross references (inserted using Word's cross-
reference field) into hyperlinks. However, you can also insert hyperlinks
using special character styles. It will even automatically insert hyperlinks
based on the relationship between topics. For example, it will insert links
from a topic to all its subtopics (the topics that are immediately below it
in the table of contents hierarchy).
Finally, Doc-To-Help enables you to highlight a piece of existing text and
use the "Add Topic Link" button on the Doc-To-Help toolbar enabling you
then to choose from a list of topics within the project (which you can filter
and sort to your own requirements):

MarcomTeam Page 18
Creating a Table of Contents
By default, Doc-To-Help creates a table of contents for a Help project
automatically, based on the sequence and heading hierarchy of topics
within the source Word documents. However, you can override this
default structure by editing the table of contents within the Doc-To-Help
project window. This enables you, for example, to permanently remove
specific topics so that they are still a part of the project, but not listed in
the table of contents. You have to keep in mind that, having edited the
table of contents by hand, new topics are not subsequently added to the
table of contents automatically.
Creating an Index
Doc-To-Help uses the index entries inserted through Word's own indexing
function. However, you can supplement these by entering new keywords
within the Project Editor—Doc-To-Help stores these keywords within a
database (not within the Word document).
One of the most powerful features of Doc-To-Help is the ability to analyze
the content of each topic and automatically generate suitable keywords
through scripts. Note that this feature is not a simple point-and-click
interface, and does require VBScript expertise. As an example of how you
might use it, you could develop a script that would process a set of topics
titles of the form "Adjective Noun" and automatically assign the following
keywords to each topic:
adjective noun
nouns
nouns, adjective
You can also use scripts in a more restricted way to modify the automatic
keywords assigned by Doc-To-Help, for example, to change them to lower
case.
Using Conditional Content
Conditional content is one of the hallmarks of a true single-sourcing tool.
Doc-To-Help enables you to build different outputs, customized for
specific formats or purposes, from the same source project.
Doc-To-Help supports conditional text, but, rather surprisingly, does not
enable you to flag entire topics within its database as being conditional.
To mark text as being conditional, you highlight the text within Word and
click the "Apply Conditional Text" button on the Doc-To-Help toolbar. The

MarcomTeam Page 19
following dialog then appears, and you have to choose between making
the text conditional to a specific platform, Help target, or attribute.
Generating Help Targets (producing online or paper-based output)
A "Help target" is the term that Doc-To-Help uses for a specific output
format. The following Help targets are available:
 HTML Help 1.3
 WinHelp 4
 Plain HTML
 JavaHelp
 Word (printed documentation)
You can create your own custom Help targets (which might include certain
configurations of conditional topics) but these would be based on one of
the standard formats listed above. According to the documentation, you
are able to create a Help target for Microsoft Help 2. However, you need
to have Microsoft's Help 2 compiler installed in order to do that, and
Microsoft has postponed its general release of the Help 2 compiler until at
least 2003.
Help target (output format) generation occurs in two distinct stages. First,
you have to "Compile" each of your source Word documents. This stage
involves Doc-to-Help analyzing the styles within the document and
creating a RTF version of each document using its own special markup.
During the compile stage, it also creates the appropriate output format for
each of the topics—so for HTML-based formats, it creates a set of .HTM
files.
Following that, you "Make the Target"—this is the process of creating any
additional files required for the output (style sheet, table of contents file,
index file, project file, etc.), and then (in the case of HTML Help and
WinHelp) using the appropriate compiler to produce the final compiled
file.
You initiate the entire process with a single button-click, but it can take
quite a long time to complete (several minutes for a large project).
However, it's much quicker than it was in previous versions of Doc-To-
Help, because the processing is done using compiled code outside of
Microsoft Word, whereas the compilation and build process in previous
versions of Doc-To-Help was executed within the Word environment using
Visual Basic. Another reason for the increased speed is an "incremental
build" facility, which means that only the source documents that have
changed since the last build are compiled—previous versions of Doc-To-
Help always processed every file in a project.

MarcomTeam Page 20
Key Strengths
 The ability to create a variety of online Help formats from a
standard Word document with minimal post-processing
 Access to the powerful word-processing features built into Microsoft
Word
 Conditional text that enables customized versions of the Help
 Powerful and flexible indexing capabilities
 Useful automated linking based on the topic hierarchy
ForeHelp
ForeHelp Feature List
VISUAL AUTHORING ENVIRONMENT
 WYSIWYG environment displays topics as they appear in WinHelp
without RTF codes
 Standalone authoring environment does not require Microsoft Word
 Full-featured word processor provides paragraph and character
styles, including bullets and numbering
 Specialty Table Editor
 Spell checker and Thesaurus
 Instantly create and edit links, macros, and other WinHelp features
with no delays for parsing RTF codes
 Customizable toolbar—choose from over 60 commands
Instant Testing
 Instant, complete simulation allows fast and frequent testing
 All help features are functional in Test Mode (macros, multimedia,
links, CNT file, secondary windows, etc.)
 No need to compile the help file prior to or during testing
Topic Navigator
 View topic list and navigate to topics from the Topic Navigator panel
in the edit window
 Docks left or right, sizes, and floats
 Display topic list in any order: by table of contents, keyword,
printed manual, topic status, topic type, alphabetical, browse
sequence, build, or author-defined order
 Create custom groupings of topics using hierarchical folders. Group
topics by help author, by function, by help file, and more
 Tab control allows easy switching between different views of the
topic list

MarcomTeam Page 21
 Topic Navigator is available for selecting topics in all applicable
dialog boxes
Navigation Techniques
 From within Edit Mode and in addition to the Topic Navigator,
navigate using all menu options and shortcuts your end users can
and more:
 Back
 Next and Previous in Browse Sequences
 Contents
 History
 Keyword Index
 Next and Previous in Topic Navigator order
 Control+Click on jumps, popups, macro hotspots, segmented
hypergraphics, buttons
Topic And Link Creation
 Create new topics with the New Topic menu, in the Contents Editor,
or by designating a new topic as a hotspot destination
 Specify topic status: In Construction, Complete, Needs Review, Out
of Date or create your own status categories
 Specify topic type: Overview, Popup, Procedure, Reference, or
create your own custom types
 Set properties on multiple topics or delete multiple topics in one
step
 Create hyperlinks by highlighting topic text, choosing jump, popup
or macro, and selecting the destination topic
 Create multiple links and topics simultaneously by selecting over a
list of topic names
 Select topic display mode: current window, secondary window, or
popup
 Create external jumps to internet sites and to topics in other help
files
 Copy topic
 Generate table of contents by clicking topics and adding their
names to a list of jumps or popups
Contents Editor
 Create new topics as you add entries to quickly prototype entire
help projects
 Create a contents file with Contents, Index and Find tabs
 Use drag-and-drop editing to add topics from topic list and visually
arrange entries into a hierarchical structure of book and topics
 Flags broken links to topics that have been deleted and deletes the
link on command

MarcomTeam Page 22
 Include topic and index entries from external help files
 Displays which topics have been assigned and which are not
assigned
 Print the Contents
 Expand and collapse the Contents for efficient editing of large help
projects
Keywords/Index
 Use drag-and-drop editing to assign main keywords and
subkeywords
 Select from a menu of existing project keywords or add new
keywords to any topic
 Edit keywords or assign secondary keywords across multiple topics
in one step
 Create text (mid-topic) keywords
 Create reports on topics per keyword, keywords per topic, and the
master keyword list
Graphics And Multimedia
 Insert BMP, WMF, GIF, JPG, PNG, SHG and MRB files
 Supports 256-color and 24-bit graphics
 Displays all graphics in Edit and Test modes with no performance
penalty
 Includes an integrated SHG (Segmented Hypergraphic) editor for
easy placement of hotspots on graphics
 Select transparent colors in graphics
 Add video, sound, and animation files to topics
Graphics Manager
 Lists all project graphics along with scaling, cropping, transparency,
and where-used attributes for each graphic
 Scale, crop, select transparent colors, and replace all instances of a
graphic in the project
 Preview any graphic in the project
 Navigate to a graphic’s location(s)
 Rename graphics
Paste Palette
 Place frequently used text, graphics, buttons, and hyperlinks into
Paste Palette for convenient reuse
 Add items from Paste Palette to topics by dragging and dropping
from floating paste palette or paste from a right-click accessible
context menu

MarcomTeam Page 23
Template Gallery
 Create custom topic templates for different topic types such as
Reference, What’s This Help, and Procedures
 Templates can include text, graphics and buttons as wells as styles
and topic properties
 Import templates from other projects
Related Topics Wizard
 Creates a network of Related Topics with easy-to-use wizard
 Automatically creates keywords, macros, and buttons by clicking
options—no preassigning keywords or creating macros is required
 Select specific topics from the Topic Navigator or select keywords
preassigned to related topics
 Automatically displays all topics using selected keywords
 Customize button or hotspot look and placement
 Place See Also buttons on multiple topics in one step
 Change related topic groups at any time—all affected topics are
automatically updated
Search/Replace And Hyperfind
 Search for text, special characters, formatting, styles, and
conditional content
 Hyperfind allows searching topic text, keywords, or macro
parameters; actions include replace text, make jump, make popup,
make macro, and make topic keyword
Navigator
 Displays a graphical view of links into and out of highlighted topics
 Displays the type of link: jump, popup, browse sequence, related
topic, interfile, remote web, contents, macro links
 Flags and navigates to broken links
 Prints any display with customizable font
Reporter
 Generates over 20 predefined reports on all or selected topics
 Reports on 25 different topic properties including context strings,
context numbers, browse sequences, jump and popup destinations,
related topics, status and To-Do lists
 Lists all project keywords and the topics associated with each
keyword
 Lists all RTF files in the project and the topics included in each RTF
file

MarcomTeam Page 24
 Project reports include topic count, file size, browse sequences, and
completed tasks
 Sort on any field (including reverse order and multi-field sorts)
 Format, search, print, and export reports
To-Do Lists And Project Status
 Create To-Do Lists for each topic and for the entire project
 Designate To-Do Item, Priority, Completion Date, and Description
 Report on completed items, not completed items or all items
 Generate reports on all or selected topics sorted by status, priority,
or completion date
Conditional Content
 Select text, graphics or topics and indicate the conditions in which
the selection is to be displayed or included in the final help files—
HTML, WinHelp 95, or WinHelp 3.1.
 Create your own conditions for review comments, different versions
of the help file, and more
Macro Editor
 Lists WinHelp macros and prompts for associated parameters
 Ensures valid parameters and syntax
 Creates named macros and macro sets for easy reuse throughout
the help file
Browse Sequence Editor
 Easily select and arrange topics into one or multiple browse
sequences
 Automatically adds browse buttons to button bar
 Navigate through browse sequences in test and edit modes
Window Editor
 Create help windows with custom sizes, colors, buttons, and macros
 Define size and position with drag-and-drop editing
 Preview window as it will appear to end-users
Reviewer’s Comments
 Create a "Review Comments" condition to mark text which will not
be built into the compiled help file
 Search project for review comments
Printed Document Creation

MarcomTeam Page 25
 Create an RTF file without WinHelp codes for importing into any
word processor or document layout program
 Select the topics and their order in the file
 Collate popups as footnotes or as a glossary
 Flag topics or topic content to be output to the printed document
only
 Generate a table of contents, index, and page numbering
Document Import
 Import formatted document files from any standard word processor
including Microsoft Word™, Word Perfect™ and FrameMaker™
 Create topics on page breaks or on selected styles
 Import styles from the document or map document styles to project
styles
 Convert index entries to keywords
Help Project Import
 Seamlessly import and export help projects to and from any help
authoring tool
 Preserves formatting, styles, and topic ordering
 Option to map imported styles to ForeHelp styles
Context Linking
 Generate context numbers automatically for each topic and export a
context map file
 Import context map files from C, C++, Visual Basic, and Pascal
applications
Adobe Captivate
Adobe Captivate (formerly RoboDemo) is an electronic learning tool
for Microsoft Windows which can be used to author software
demonstrations, software simulations, branched scenarios, and
randomized quizzes in .swf format. It can also convert Adobe Captivate
generated .swf to .avi which can be uploaded to video hosting websites.
For software simulations, Captivate can use left mouse clicks, key presses
and rollover images. Adobe Captivate 3 cannot simulate right mouse
clicks without editing the files that are generated, but with Adobe
Captivate 4, this is now possible.
Features

MarcomTeam Page 26
Captivate builds and edits interactive software demonstrations,
simulations, podcasts, screencasts, games, program demos and lessons.
For software demos, it can either record in real time or use an event-
based screen capture that snaps a sequence of still images and then
builds mouse movement simulations to create the appearance of a
running program. By using Adobe Flash Tweening technology, Captivate is
able to create screencasts in a much smaller file size than needed for a
real full-motion screen capture movie.
Captivate users can edit Captivate presentations to add captions, clickable
hotspots, text entry boxes, rollovers, videos, etc. Authors can edit the
content (including mouse pointer path, position, image) and change the
timing for each item to appear and disappear. The hotspots can branch to
other slides in the presentation, or to outside webpages. E-
learning authors can also provide multiple levels of feedback using
multiple interactions per slide.
Captivate supports the import of still images, PowerPoint, video, .flv, and
audio tracks onto any Captivate slide.
Captivate also supports 508 compliant (Accessibility)
output, SCORM, AICC (CBT), and PENS (software) to track score data
in Learning Management Systems (LMS).
 Multimode recording Save time and generate robust software
simulations with multiple learning modes in a single recording
session, including a demonstration of the procedure, a simulation
for practicing the steps, and an assessment.
 Randomized quizzing and question pools Improve learner
assessments by randomly drawing questions from a set of question
pools. Shuffle the answer options for multiple-choice questions, so
that the answers are displayed in a different order each time. Share
question pools among multiple Adobe Captivate projects.
 Rollover slidelets Provide additional just-in-time information on
Adobe Captivate 3 slides by displaying mediarich content including
images, text, audio, and video in a slidelet (a mini-slide within a
slide) when the learner moves the mouse over a specified area on
the slide.
 XML export and import Simplify the localization process of
projects; export captions to a text or XML Localization Interchange
File Format (XLIFF) file. Import the translated text file into a copy of
the original project file.
 Automated rerecording Quickly update content and automatically
rerecord entire procedures in most web applications after the user
interface is modified or localized (Internet Explorer® 6).
 Animation effects Create learning content with support for
animated slide transitions and PowerPoint® animations. Import

MarcomTeam Page 27
PowerPoint (PPT) files and retain many animation effects by
converting PowerPoint slides to SWF files.
 Audio recording with preview Synchronize audio easily with
slides and timed objects. Record narration while previewing slides in
real time by going through them one by one or as a complete
project.
 New question types Increase learning effectiveness with
specialized question types, such as sequencing and hotspots, and
matching dropdown lists.
 Rich media support Record audio from system or through line-in,
in addition to microphone.
 Full motion recording Record full motion movies in SWF format
that show detailed motion such as drawing/painting features and
drag/drop operations.
 Streamlined workflow and usability enhancements: Work
faster with a wide variety of streamlined workflows and usability
enhancements:
o Find and replace
o Enhanced screen recording for capturing screen activity
o Real-time recording mode
o Improved learning management system (LMS) integration
o Reusing quiz slides
o Reducing SWF file size
o Branching view enhancements, such as slide grouping and
zooming
o New choices for adding captions and buttons
For more technical writing tools, detail information and training get in
touch with us at techwriting@marcomteam.org

Technical writing tools

More Related Content

What's hot (20)

Viewers also liked (8)

Similar to Technical writing tools (20)

Recently uploaded (20)

Technical writing tools