WritersUA - Training and Information for User Assistance Professionals

Single Source Publishing with Flare

By Petra Thiemann

Bookmark and Share


Contents

Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.

Introduction    Link to contents

Single source publishing is an issue that is often discussed from various angles. The concept comprises two main principles:

  • Information supplied from one source for a range of media, e.g. print or online
  • Using information from one source repeatedly

Initially the reader/user (writer) doesn't benefit from single source publishing. This is because it's not obvious whether the text they are reading comes from a single source publishing Project or is written in a normal word processing program. First and foremost, single source publishing is an aid for editors, which helps them use data effectively for creating user documentation.

In the best case the reader benefits directly from single source publishing through:

  • Consistent terminology
  • Consistent information (data) (same description for the same content)
  • A useful accordance between the information provided on various media

But these points also show the potential weaknesses of single source publishing, especially when it's used without a concept. And this concept involves work, which is not immediately obvious. The more detailed the concept for single source documentation, the more effective its use.

Flare is a help authoring system (HAT) which took up the cause of assisting single source publishing. It has a wide range of functions which enable you to use single source publishing. Flare is ideal for single source publishing based on the XML approach (separating the content from the format) and the topic-oriented approach (separating the description, instruction and reference). The same ground rule applies to both single source publishing and Flare: Without a concept the multiple functions of Flare cannot be used to their fullest.

In practice this means: If you opt for single source publishing, it is essential to develop a manageable concept which is documented and communicated.

Development of a Single Source Publishing concept    Link to contents

In order to develop a single source publishing concept, you should be able to answer the following questions:

  • Is single source publishing useful for my kind of documentation in any way?
  • What principle do I want to fulfill?
  • Which basic approach do I want to follow (top-down or bottom-up)?
  • Which of the single source elements do I want to use?
  • Do I have enough time to develop and maintain a concept?

When Is It Useful to Use Single Source Publishing?

This question has to be answered by the editors themselves, as there are no general guidelines. You can't simply base single source publishing, for example, on the size/complexity of the product or its degree of modularization alone.

It's very useful to create a list of pros and cons for single source publishing to help you answer the question above. Possible questions could include:

  • Am I creating documentation for a product that:
    • is offered through various media (Help, manuals, websites, etc.)?
    • is aimed at different target groups (Getting Started, Administration, User Guide, brochures, spec sheets, etc.)?
  • Do I have information (data) that is used throughout the entire documentation in different places, e.g.
    • Pictures
    • Notes (instructions)
    • Warnings
    • Whole passages, e.g. descriptions of parameters
  • Am I documenting a product
    • that contains several modules with a mutual basis (same layout, same window structure, joint dialogs, etc.)?
    • for which this modularization is planned?
  • Am I documenting several products with a high functional level of compliance, e.g. a series?

These questions are not set in stone, nor are they complete, but they need to be answered and extended within each documentation project. They indicate the direction to be headed and they also show that single source publishing can be useful for smaller projects as well.

Single Source Principles

Single source publishing is mostly initiated by the wish to supply information from one source for a range of media in order to keep creation effort low and contents consistent. However, soon you reach the point where you have content that could be used in more than one place. This means that single source projects in most cases meet both principles named at the beginning.

Concept Approach

To develop a single source publishing concept there are several approaches, the most common being top-down or bottom-up. Although you already use particular elements of single source publishing (bottom-up), it can be rewarding to take a step back and look at your documentation project with "new eyes" (top-down).

With single source publishing it's first important to determine the functional framework, which can be defined with the following questions:

  • Which products are to be included?
  • Which documents are to be included?
  • How many target groups are to be reached?
  • How many media are to be catered for?
  • How many authors will work on the documents?

Once the functional framework is in place, it's easier to judge which single source elements are required. As well as the framework, there is the question of complexity: the more products, media or editors are involved, the more explicit and simple a single source concept should be.

Single Source Elements    Link to contents

The elements described here are based completely on Flare. Similar or different elements are used with other editors. Flare offers a whole range of functions for single source publishing, the most important being:

  • Master-project linking
  • Topics
  • Snippets
  • Table of contents
  • Targets
  • Variables
  • Conditions

I will discuss these elements in brief below. The listing already emphasizes the top-down approach.

Master-project Linking

The larger the quantity of shared information within a single source publishing project, the more useful master-project linking will be. The principle behind master-project linking is that all shared information is stored in one master project. If you are describing products or product components with a high degree of compliance, using single source master-project linking is ideal.

Layout information and content used in more than one product project are created and maintained in a master project. Only product-specific information is held in the individual sub-projects.

To build the printed output, all information needs to be present in a Flare project. Therefore, the relevant information has to be imported into the sub-project from the master project. Flare offers a convenient import function that can be saved as a template in the sub-project and reused when necessary.

Figure 1: Import dialog box

Files imported from another Flare project are marked with a "key" symbol and can only be edited after confirmation.

Topics

Topics are the basis because they contain the information for your readers. A lot has been written about how to modularize content, so I will just summarize briefly here: Even if you don't use the DITA schema, the DITA principle offers a convenient template for single source publishing. The main message of DITA is basically to separate description, instruction and reference and describe them in different topic classes.

As a result, this means that in a single source publishing project there are at least three topic templates: one for descriptions (e.g., introductory text), one for instructions (step-by-step procedures), and one for reference information (GUI or command descriptions). Following the DITA approach further, you can define exactly the structure of these topic classes, i.e. which contents are allowed and which not.

Figure 2: Topic class procedure

The allowed contents need to be formatted, which means that the preparation of the individual topic classes automatically produces a basic style sheet.

Snippets

Snippets contain information shared between more than one topic. They are author-specific auto-text, so to speak. A snippet may contain a single sentence or just a phrase, but it may also contain entire paragraphs, pictures, tables or lists.

The smaller the content contained in a snippet, the more it can be shared. But: the amount of snippets may increase enormously, along with the effort of checking and searching.

Therefore a higher degree of fragmentation is recommended. Use snippets at least on the basis of paragraphs and use an Authoring Memory System to control the consistency of frequently used sentences and phrases. Especially if more than one author is working on the project, an Authoring Memory helps standardize the writing style.

From the technical perspective a snippet is a "headless" topic (head tag) and is ideal, for example, for parameter or button descriptions. The more snippets you create, the more helpful it may be to document the snippets - not only to keep track of your snippets but also to help your successors or (temporary) co-authors quickly get up to speed.

Table of Contents

Tables of contents are not generated but are created manually, because not all your project contents will always need to be built into an output. A table of contents provides a logical structure for accessing the information and it suggests a hierarchical order. But Flare also uses the table of contents as a control file to build the printed output. Therefore the table of contents has two functions, which are indicated by two terms:

  • TOC stands for the logical function
  • Outline stands for the control function

Both refer to the same file type, fltoc, within the project organizer. Two terms with two different meanings for the same thing can be a constant source of misunderstanding, even though you can follow the underlying logic after a while.

You can work with a single TOC or outline in Flare or create a TOC for each output format. Especially if different content is linked to different output, working with multiple TOCs pays off.

In an outline the entries can be linked with various control and layout information.

Figure 3: TOC entry properties

You can, for example, determine the chapter page number of each entry in the TOC. Each chapter can be linked with a page layout. Thus you can specifically control the appearance of the printed output.

Targets

A target is the information hub for an output. It's the control file that defines which output format is to be compiled. Targets can be created for the following output formats:

  • HTML Help (file extension .chm)
  • DotNetHelp
  • WebHelp, WebHelp AIR, WebHelp Plus (browser-based help)
  • Word document
  • FrameMaker document or book
  • PDF document

A project can include an unlimited amount of targets for any output format. For example different targets can be added for help files or books that are geared to different target groups.

A target combines layout settings and contents with the output format, for example:

  • Master page
  • Page layout
  • Glossary
  • Variables
  • Conditions

This means that anything that influences the compiled output is connected to the target.

Variables

Variables are well-known in the programming environment and Flare uses and handles them in the same way. First, variables need to be declared. This happens in the so-called Variable Tag Set. Here an author declares which variables they intend to use and the initial value of each variable.

Especially if you are describing more than one product in your single source project, you could use a variable "product" that will contain the respective product name. If, for instance, the release management is different or volatile, a variable "version" might be helpful. With an elaborate Variable Tag Set an author can circumvent unnecessary conditions.

Next, variables are inserted into topics or layout files such as page layouts or a master page related to their intended use. In the source files variables always show their initial value. Unlike snippets, variables are formatted according to the paragraph they are inserted into.

The actual setting of a variable happens in the target.

Figure 4: Target, Variables tab

Here the author sets the values for the variables as they are to be used in the output. Variables not set in the target keep their initial value. Flare thus offers very flexible handling of variable content tailored for the respective output.

Conditions

The use of conditions is common in many publishing environment. Conditions determine which information is built into an output. This makes sense if you know that Flare generates all information present in the project into a help output. If you want to use Flare for single source publishing and keep your online help succinct/compact at the same time, conditions are a must.

Like variables, conditions are declared in a tag set. But conditions are related to colors, not initial values. You can assign one or more conditions to:

  • One or more characters
  • One or more passages
  • One or more listing elements
  • A list
  • One or more chart rows or columns
  • A chart
  • A picture
  • A topic
  • A control file
  • An index

Information labeled with a condition is highlighted in the related color. If this display is switched off, the color is only visible in the XML structure bars. The rectangle in front of a file labeled with a condition displays the related color.

The actual activation of the condition happens in the target.

Figure 5: Target, Conditional Text tab

Similar to hide and show conditions in FrameMaker, here the conditions are excluded or inserted for the build. Flare applies conditions according to an exclusion principle, meaning that initially everything is displayed and generated. Information labeled with a condition that is excluded in the target is not generated into the output.

Information in more complex single source projects can be labeled with several conditions. If one of the conditions used is excluded, the information is not generated. In this case, including is relevant: In the case of multiple labeling, the included condition overrules the exclusion principle.

If some information is missing from your output, this might be due to an excluded or not-included condition. To check the outcome of excluded conditions in your topics you can use the preview with conditions.

Figure 6: Preview with condition set

As a further step, you can use conditions as a switch to show or hide certain information from an inserted snippet in a topic. In the Snippet Conditions tab of the topic properties you can exclude or include information from contained snippets.

The working principle is the same as for the target but at the topic level. In the topic, only the snippet information that is not excluded with a condition is shown. The topics containing the snippets are generated as they are displayed. Thus you can write more general snippets and tailor the displayed information with conditions.

Conditions and variables can increase the degree of complexity to a remarkable extent. For these two single source elements in particular, take the motto "less is more" to your heart. Especially if more than one author is working on the project, keep the number of variables and conditions as low as possible, otherwise they will simply not be used.

Meta Data

Meta data are an important part of a single source project because their job is to describe the type and content of an element, which can be used when searching for content.

Usually metadata are saved in a database as properties of the elements used. Because Flare is not database-based, you can only apply meta data indirectly, for instance in:

  • naming conventions for folders
  • naming conventions for files
  • special templates for special elements, e.g. topic classes

Time Management    Link to contents

It's not possible to switch to Single source publishing overnight. Single source publishing takes up a lot of time:

  • to develop a concept
  • to demonstrate the concept with a pilot
  • to enhance the concept for other projects
  • to document the concept properly
  • for adjustments for the concept and projects

Single source publishing involves a huge workload in the beginning, but this will pay off in time as you create effective documents. This start-up period has to be reckoned with.

With single source publishing the editorial department is taking a step toward data (information) development. And Flare supports them on their way.


Petra ThiemannPetra Thiemann has more than 20 years of experience as an editor and user assistance professional in the software industry. She authors various articles on user assistance. Petra holds a M.Sc.in Education from Munich University in Germany. She is also a certified Flare Trainer.

Petra Thiemann, Senior Technical Editor
cognitas GmbH
petra.thiemann@cognitas.biz
Alte Landstr. 6
Ottobrunn, Germany

up




Copyright © 2010 WritersUA. All Rights Reserved.
shannonm *at* writersua *dot* com
Published on Nobember 16, 2010


































Loading

The Conference for Software User Assistance


UI Text Design




WritersUA offers cutting-edge training and information to Technical Writers, Information Analysts and Architects, Documentation Designers, Help Authors, Publication Managers, Documentation Leads, Senior Writers and Documentation Contractors, and User Education Specialists. The focus is on software user assistance, which encompasses writing, editing, planning, coding, indexing, testing, programming, localization, and standards development.












WritersUA Home Page First Time Here Contact Us Join Our Mailing List OASIS Member RSS Resource Directory Tools Contractors Training Articles Blogs Web Resources