Content Reuse and More

There are all kinds of things you can do in Doc-To-Help. But you don't have to do them all. There are actually just a few concepts and features that are the most important to grasp. Don't expect to be an expert at everything right away. Instead, begin by trying to wrap your brain around a few concepts and features that are most important when it comes to learning Doc-To-Help. These concepts and features all tend to revolve around the idea of content reuse (or single-sourcing), which means that you can take the same content, re-use it, and produce multiple outputs from it.

Example  

One of the most common ways to single-source a project is to produce one type of online output (such as NetHelp), as well as multiple print-based outputs (Manual targets) from the same source Word document.

Another way to take advantage of single-sourcing is to use one set of documents to create output for multiple audiences, such as an Administrator version and a Manager version.

One more possibility is that you might take the same source content and generate output for different purposes, such as documentation, training, or reference materials.

You might even use a combination of these techniques. For example, you might create one desktop-based online Help system, a web-based elearning site, a PDF quick start manual for administrators, a PDF quick start manual for managers, and a PDF reference manual for co-workers. And it is all created from the same Word source content.

Following are some important questions you will likely need to answer before you begin creating files and content:

  • What kinds of output do you want to create? Do you need online output, print output, or both? How many different versions of online and print output do you need? See Output Types and Targets.
  • How will you name your files to keep things consistent and organized?
  • What kinds of variables will you need? See Variables.
  • What kinds of conditions will you need? See Conditions.
  • Will one author be working on the project or will multiple people be involved? See Team Authoring.

In other words, the more planning and preparation you do beforehand, the smoother your journey in Doc-To-Help will be.

Whether you start out with just a single Word document or have several Word files, Doc-To-Help does several things to make it easier to single-source.

  • Structure (Documents to Topics) Word documents can be relatively easy to work with, but they aren't necessarily the most conducive format when it comes to online output. That's because online output (e.g., a website or online Help system) is typically broken up into several somewhat small pages, whereas a Word document is a single presentation of information, and sometimes a quite long one at that. To make your Word document more useful for online output, it is broken up into smaller elements called "topics," which are based on the heading styles in the document (see Topics). After you create a Doc-To-Help project and build some output from it (see Building Targets), Doc-To-Help automatically creates multiple topics as a result, structuring the content for online documentation. Heading 1 styles in your Word document automatically become parent topics, and all of the Heading 2 styles under a Heading 1 style become subtopics. Just keep in mind that these topics are not created until you build at least one target in your project.

    Example  

    The following shows a project containing two Word documents, one that contains the main content and a second being used as a glossary. No targets in this project have been generated yet. Therefore, no topics exist right now.

    After building a target, notice that the Topics panel is now populated, based on the heading styles in the Word source document. In this case, multiple topics were created from the two source documents. It also shows the structure of the table of contents that will be created in the output.

    The Contents window pane in the Doc-To-Help Project panel in Word is also populated. If you are working in a source document in Word, you can use the Contents pane in the Doc-To-Help Project panel to quickly view the structure of the document, jump to locations in the source document, or create links.

  • Navigation Parent topics automatically include "See Also" links to subtopics. See Managing Related Topics.

    Example  

    The following shows a parent topic containing links to its three subtopics.

  • Links Cross-references (with page numbers in print-based Manual targets) are automatically converted to hyperlinks in online output. Also, manuals can be set up to include both hyperlinks and page number cross-references. This is useful for both types of end users—those who prefer to read on screen or print out the manual. See Inserting Cross-References.

    Example  

    Here is how a cross-reference might look in the Word source document:

    When you generate and view the PDF, the link looks like this:

    But when you generate and view NetHelp online output, the link looks like this:

  • Drop-Downs and Expanding Text Your text can be flagged so that it appears as drop-down or expanding text in online output. This text will automatically be included in the print-based output. See Creating Expanded, Drop-Down, or Popup Text.

    Example  

    Here is how a drop-down might look in the Word source document:

    When you generate and view NetHelp online output, the link initially looks like this:

    When the drop-down is clicked, it looks like this:

    When you generate and view the PDF, the drop-down looks like this:

  • Margin Notes Margin notes included in printed outputs automatically become popups in online output. See Creating Margin Notes.

  • Front Matter and Back Matter For print-based manuals, Doc-To-Help automatically generates the title page, table of contents, and index so you don't have to. This occurs if the front matter and back matter elements are part of the target template that you use. When you open the target template or generate output, you will see these elements, but when you edit your source document, you won't see them. See Templates and Styles.

It is easy to confuse output types with targets, but they are two different (although related) concepts. A target is one instance of an output type. It is the engine that takes all of your files and settings, and brings them together to produce the end result. When you build your final output, you are essentially building one or more of the targets in your project. Doc-To-Help offers several kinds of online outputs, as well as a print-based output that can be viewed in either Word or PDF. See Output Types.

When you first create a Doc-To-Help project, you'll notice that targets based on each output type are available to you. But you can remove those you don't plan to use and add more targets based on the output types that you want to publish. See Creating and Deleting Targets.

Variables allow you to write content once, and manage it in one place for reuse across your project. You might create text variables for often-used text that does not need to be formatted (e.g., product or company name, address, version number, system date/time). You can also use rich content variables for blocks of formatted content (e.g., tables, images, entire topics). See Variables.

This is where Doc-To-Help gets really powerful. Conditions are used to tell Doc-To-Help, "I want this piece of content to be in this output but not that one." For example, maybe you plan to have two versions of some online output—one version for beginners and one version for advanced users. Much of the content you create is going to be the same for both audiences, but some of it is going to be written only for a specific audience. So you can create conditions for each audience and use them to separate the content when you build output. See Conditions.

There are a few ways to control the look of your output. One method is to use styles.

If you're used to Microsoft Word, you know that styles can be applied to content to change how it looks. You can apply Word styles just like you normally would in a document that is not part of a Doc-To-Help project. However, you should be aware of the following when working in a Word document that is part of a Doc-To-Help project:

  • Doc-To-Help relies on your use of Word's heading styles (e.g., Heading 1, Heading 2) in order to break your document up into multiple topics. This is important for online outputs. So you should make sure to apply those styles to headings in your document where you anticipate new online topics should start.

    Tip If you plan to implement context-sensitive Help (see Context-Sensitive Help), you should standardize on one (at most two) heading styles that Help button topics will map to. It can be confusing to the user if multiple styles appear from Help buttons. Make sure to structure information so that Help buttons have only one logical mapping. Dialogs that are reused throughout an application can make this challenging.

  • In addition to Word's styles, Doc-To-Help has several special styles that it uses for certain features (e.g., drop-downs, popups, conditions). These styles are automatically applied to content when you use features in the Doc-To-Help ribbon in the Word document. Also, you will see these styles (which begin with C1H) when you open the Styles window in Word.

For more information, see Styles.

Doc-To-Help uses two kinds of predefined templates (DOTX files) to determine how content will look.

  • Source Templates These control the look of source documents (when you are authoring in Word). Additionally, all of the content in source templates appears in new documents created from the template, so you can use customized source templates as a way to provide structure to new documents (e.g., defining headings, providing sample text).
  • Target Templates These control the look of the final output.

Templates contain styles that you apply to your Word source document. The source styles are interpreted by the target template you have chosen so that your output looks and behaves the way you desire. Styles control your final outputs in multiple ways, and they are a convenient and efficient way to keep your content looking consistent. Therefore, it is important to use them and avoid applying local formatting.

For more information, see Templates and Styles.