Overview

To prepare your document, you must consider the style, layout, and content you wish to present.

Single sourcing begins with the creation of your base file. This file acts as a storage area for your text. All changes to content and index entries will be made in this file. Therefore the layout of this file must be approached carefully to minimize the conversion and maintenance effort later. Any Microsoft Office format (TXT, DOC, RTF, PPT, and so on) can be used as your base file. However, if you are single sourcing a HLP and PDF system, the RTF file is the preferred base file due to issues involving link and index maintenance. This page explains how to use the RTF file as the basis for your entire documentation set. Follow these steps to create an efficient single source from an RTF file:

  1. Create an outline.
  2. Save the outline.
  3. Start a new document based on the Online97.dot template.
  4. Copy your outline into this document.
  5. Write your text using the guidelines in this section.
  6. Save your document as an RTF file.

Note: Use a separate RTF for each chapter of your document. If you are creating a help system rather than an online guide, use a separate RTF for each type of information (tasks, windows, concepts).

You must be familiar with the concepts of WinHelp construction to effectively create a base WinHelp system. For more information on creating a WinHelp system, see your HCW online help.

Note: Create a rigid directory structure prior to beginning your project to improve your ease of maintenance later. To create a rigid directory for conversion and maintenance, follow these steps:

  1. Create a project directory.
  2. Beneath the project directory, create three subdirectories: RTF, DOC, and ART.
  3. Place the RTF, HPJ, CNT and HLP files in the RTF folder, DOC files in the DOC folder and all graphic files in the ART folder.

    4. This method allows you to move your project from place to place with little to no interruption in your links.

    Creating an Outline

    The outline is your most powerful tool. By creating an outline, you can structure the information in a logical manner, avoiding loops and deadend links in WinHelp, ensuring good flow and continuity in DOC files. Your outline should be structured as strictly as possible. You can use this outline to produce your RTF, DOC, your CNT files. The following guidelines can help you create an effective outline:

    1. Avoid single subheadings beneath a heading. For example if the heading is Installing the Product, you should have at least 2 subheadings, such as Prerequisites and Installation Steps, beneath it. For WinHelp, this method prevents your user from running into a deadend. A subheading that is the only thing on its level is difficult to link to other headings through means other than a browse sequence. Ideally, the user should always have more than one way to leave a topic. For DOC files, this method improves the flow of text, ensuring you present the material in a logical fashion.
    2. Never have two sections cover the same information. Due to the dynamic nature of WinHelp, repeating information is completely unnecessary. If you need the user to have the information in more than one location, use a link. In DOC files, repeating an entire section of information indicates poor flow. Consider carefully how to structure your information to make the most sense for the user.
    3. Ensure that all your headings on a level use the same language. That is, if your first Heading One is a question (What is an OLE Link?), all of your Heading Ones in the chapter should also be questions. Ideally, make your headings task-oriented (Defining OLE Links) - tasks help the user understand exactly what they can accomplish in a given section of material.
    4. Keep your headings short. In WinHelp, long headings force the user to scroll right and left to view the entire heading. In DOC files, long headings can confuse the user, obfuscating the information they need to extract.
    5. Ensure that your chapter flows in a logical manner. Imagine yourself using the product - what steps would you take and in what order? The answer to that question should drive the order your outline follows. Break your chapters at each logical break in the use of the product (understanding, installing, customizing, using)
    6. Streamline the information. Put all reference material in appendices. Put all term definitions in the glossary. This method avoids unnecessary repetition of information and groups data in logical places for the user.

    Important! Your outline is the most important document produced when creating your documentation. This piece contains all the relevant information about your documents and serves as a roadmap for others who may need to maintain your document later. If you make changes to your headings, always include these changes in the outline. You can use your outline for localization efforts, handoffs, proposals, project estimates, and so on.

    Chunking Your Information

    Chunking is a style of writing in which you isolate the types of information you are using. Information falls into 3 main categories:

    Concepts teach a user WHY he wants to use this product. Definitions tell the user WHAT the parts of the product are that he can use. Tasks tell the user HOW to do something with the product. Chunking gives the user exactly what he wants, when and where he wants it. This method allows people with different learning styles to use the same document effectively. In addition, chunking is essential for effective OLE single sourcing. By keeping the information in discrete packets, you can take those packets and arrange them in any way, producing many different presentations with the same material.

    Creating and Linking Your Graphics

    Graphics are one of the most powerful, misused, and misunderstood aspects of documentation. A picture can clarify an idea or obfuscate it. Before putting screen shots into your help or hardcopy document, consider whether the picture helps the user. Screen shots representing popup windows that contain some text and an OK button should always be eliminated. In addition, developers are always updating screens at the last minute. To avoid constantly having to recapture all of your windows simply because the capitalization of a few fields have changed, try to limit screen shots to parts of windows. This technique saves time during delivery and maintenance.

    Creating Graphics for Compatibility

    Choosing the right format for your graphics can greatly reduce the amount of time required to maintain and link your document. WinHelp accepts two types of graphic formats that we will consider:

    DOC files can also use either of these formats. By choosing to use BMP or WMF, you can avoid maintaining multiple sets of graphics (TIF, GIF, etc). This method minimizes the amount of maintenance you must perform when a screen shot or diagram changes.

    Linking and Directories

    Linking graphics refers to the process of placing a pointer (for WinHelp a {bmc} field, for DOC files a picture link) in the file instead of pasting the picture into the file. Linking is the only type of graphic inclusion that Microsoft supports. Embedded graphics are large, unwieldy and unstable.

    Note: When creating linked graphics, you create a pointer to a real location. That location must remain stable in order for the link to work.

    To ensure that your graphics are centrally located, follow these steps:

    1. Create a subdirectory to your main project directory called ART.
    2. Place all graphics for this project into this directory.

    Creating an Index

    Creating an index is the most difficult task the technical writer must accomplish. The index is usually the last thing you create on a project and the first thing at which your user looks.

    The DOC to RTF conversion macros often produce awkward indexes in WinHelp. This problem occurs because information that was previously on five pages in a DOC file is now one large "page" in the WinHelp file. All of the index entries for that page will take the user to the top of the section, making the index difficult to use. In addition, WinHelp files support only two levels of indexing, while most of our DOC files have three levels. This difference requires significant clean up efforts after a macro conversion.

    In contrast, creating an index for OLE single sourcing is relatively easy. Since you have chunked your information in your RTF, all of your index entries will be focused and concise. To ease the linking process, create both DOC and RTF index entries at the same time.

    To create your index, follow these steps:

    1. Decide on your index entry (for example, Index, creating).
    2. In the keyword footnote field, enter your index entry.
    3. Copy your index entry.
    4. Page up to the paragraph to which the index entry applies (often this will be the only paragraph on the page).
    5. At the end of the paragraph, insert an index field {xe " "}. You can insert this field through Word the same way you would have done in a DOC file.
    6. Paste your index entry between the quotations in the index field.
    7. Replace the comma with a colon.
    Repeat this process for all index entries.

    Tips: The following tips will help you create a better index:

    1. Always consider inverting your entries. (for example, Creating, index and Index, creating). This approach provides more places for a user to find your entry.
    2. Always put your index field at the end of a paragraph. This method ensures that you will not have spaces at the beginning or in the middle of sentences. Do not put the entry inside the paragraph because this can lead to accidentally over-typing your entry.
    3. Never put your index entry in a heading. It will not be carried over in the conversion process and can cause errors during compiles and TOC generation.
    4. Always check your index for duplicate entries, consistent language, plurals, and spelling errors.
    5. Keyword index entries do not need to be tied to the heading. If you have a long page of information, consider putting your K footnote entry near the term, rather than at the heading.