FrameMaker 10: Using Element Descriptions to cut down writers’ training costs and efforts


Prolog

The guided-tour like authoring experience of FrameMaker just got even better. In addition to the structured view, element catalog, and view elements as tags, FrameMaker 10 displays element descriptions next to the element names in the element catalog. This article introduces Element Descriptions and illustrates how you can port additional text/help that appears next to the elements in FrameMaker for writers, resulting in savings in the cost and effort involved in training new writers.

Element Descriptions

FrameMaker 10 further simplifies structured authoring by displaying description of the various elements next to the elements.

Structured FrameMaker 10 with default Element Descriptions in Element Catalog

You can edit the element descriptions to provide contextual, element-level help to your authors. A good, thorough implementation of these descriptions can save you time, effort, and money and will be especially useful for the new authors in the team. You can do this with a fraction of the cost and effort of having to train new writers about the vocabulary (i.e. elements) of your structured applications.

The process to insert/edit element descriptions

Using the DITA 1.2 task template as example, the following steps illustrate how you can augment the textual descriptions of your templates to simplify the task of using structure even further.

Step 1: Export the element definitions of your template as an EDD.

1.       Open the relevant structured template .fm file and select StrutureTools > Export Element Catalog as EDD. (See structapps.fm for the name and location of the template file.)

FrameMaker creates a new document as an EDD that includes the structure and the elements of the template.

2.       Save this document.

Step 2: Add/Edit the Descriptive Text element in the EDD.

1.       In the EDD, locate the element tag in the EDD that you want to edit.

2.       After the “Container” tag in the relevant element tag, insert the DescriptiveTag element and type in a description relevant to the element. If the DescriptiveTag element is already present, you can edit the description.

Step 3: Import element definitions to the template from the EDD.

The element descriptions you typed into the EDD are now in template. Now when you create a new document based on the updated template, you see the element descriptions next to the elements in the Element Catalog. The figure below displays the edited descriptions of the elements prolog, related-links, shortdesc, task, and taskbody.

Over time, edit the descriptions recursively to address the doubts and frequently asked questions of your writers for various elements.

, , , , , , , ,