Customizing Content with DITA Conditional Text and XMetaL

in 37 minutes
Episode 9Customizing Content with DITA Conditional Text
Su-Laine Yeo, Solutions Consultant
July 15, 2010

Conditional text with the DITA (Darwin Information Typing Architecture) XML language
Practical steps for using conditional text in XMetaL Author Enterprise
Fairly detailed level, but not difficult
Specific examples
Not using DITA? Keep watching, and also come back for our next 37-minute webinar on July 29
Today’s webinar

Customization and content reuse
Reuse lets you deliver customized content without duplicating it
Approaches:
Modular reuse:
reusing whole topics
content references (conref) to reuse phrases and parts of topics
Conditional text

What is conditional text?
“Conditional text” refers to:
The practice of marking up the content in a single source file, so you can create deliverables with different subsets of the file.
The contentthat is marked up so you can filter it out of some deliverables. In DITA,conditional "text" can be words, images, tables, index markers, links, etc.

Conditional text
Marking up the content in a single source file, so you can create deliverables with different subsets of the file.
E.g. Windows-only content (Ctrl+S) and Macintosh-only content (Command+S)

attribute
attribute value
Under the covers: XML
A paragraph that is not conditional:
Press Ctrl+S.
A paragraph that applies to the Windows platform only:
Press Ctrl+S.

Steps for using conditional text
Plan
Make a list of your audiences, products, and platforms that require similar documentation
Configure
Configure the system to use the conditions you want
Style conditional content so that you can keep track of it when writing
Write
Mark content as conditional
Generate output
Choose a particular product/platform/audience combination

Make lists:
What product variations are similar enough they could be documented through one set of source files?
What audiences do you want to customize documentation for?
Example for today’s webinar: two platforms
A software application that has different keyboard shortcuts for Macintosh and Windows platforms
Step 1: Plan

Step 2: Define conditional attribute values
Edit the XMetaL ditabase_ct_config.xml file.
This file is installed in your C:Program FilesXMetaL 6.0AuthorConditional Textconfigs folder.
<attribute name="platform" title="Platform">
<value name="windows" title="Windows" />
<value name="macintosh" title="Macintosh" />
</attribute>

Distribute settings files
You can standardize conditions within a team by distributing the ditabase_ct_config.xmlfile.
When you start XMetaL, XMetaL automatically configures its Conditional Text dialogs to use the values in this file.

Style conditional text
You'll want to be able to keep track of conditions when you are writing, preferably in real-time via color-coding.

Configure styling
Styling affects what you see in XMetaL, not in output
Click Reuse > Style Conditional Text.

To make content conditional:
Click in an element, or select some text
Click Reuse > Apply/Remove Conditions
Step 3: Write

Under the covers
Content for Windows only:
Press Ctrl+S.
Content for Windows and Macintosh, but not Unix:
Press Ctrl+S.
Content for all platforms:
Press Ctrl+S.

What content can you make conditional?
Yes:
Text
Images
Cross-references
Index markers
Tables
Rows in tables
Content within content references
Topic references in DITA maps
No:
Individual table cells
Table columns
Required elements (you can conditionalize text within required elements)

<ph> element
If you make selected text conditional, XMetaL inserts <ph> tags so it can “hang” attributes on the <ph> element.

Best practices
To make a whole topic conditional, conditionalize the corresponding topic referencein the DITA map file.
Do not conditionalize content that is "common to all."
If an element is common to all deliverables, do not put conditional attributes on it.
If an element is common to all products, do not put any "product" attributes on it.
If your content will be translated, it is safest to conditionalize entire sentences, not parts of sentences.

Step 4: Generate conditional output
In XMetaL: File > Generate Output
Choose what platforms, products, and audiences you want to include

What about DITAVAL files?
<prop att="platform" val="macintosh" action="exclude"/>
You don’t need to write one. XMetaL generates the DITAVAL file automatically:

Multiple Condition Types

Multiple condition types
Say you have:
Three platforms: “Windows” and “Macintosh” and "Unix"
Two audience types: “Europe” and “North America”

How DITA handles multiple condition types
For an element marked as audience = “Europe” and platform = “windows”
*Would appear if you used native FrameMaker® conditions instead of DITA

Multiple condition types: the rule
In this example: Content must be for both the right platform and the right audience in order to be included.
The general rule: An element is included if, for each conditional attribute:
It doesn't have any values for that attribute, i.e. it is "common to all"
OR it matches at least one value that should be included.

Of the 4 steps, planning is the most challenging:
Plan
Configure
Write
Generate output
Putting it into practice

DITA attributes
DITA attributes for conditional text are:
product
platform
audience
otherprops
For anything else, including other audience types
props
Create new attributes by specializing the “props” attribute

Example
You are documenting a product with Macintosh, Windows, and Unix versions
For this example:
the attribute you need is "platform".
you will allow the values of the platform attribute to be "Macintosh", "Windows", and "Unix".

List the attributes, and values of each attribute, that you want to use.
These will go into your ct_config.xml file
Do not overload the “audience” attribute:
E.g. have an “audience_skill_level” attribute and a “audience_region” attribute. Do not put your lists of skill levels and regions all into the “audience” attribute.
Make lists

Summary: Why DITA for conditional text?
Scalable:
Handles multiple condition types well
Easily standardized across a team
Standards-based:
Multiple output formats
Can work with dynamic content delivery systems
Within reach:
No programming needed
Does not require a sophisticated CMS or publishing system

Q&A
Contact Su-Laine at: syeo at justsystems dot com
Today’s slides are at http://www.slideshare.net/XMetaL
contactsales-na@justsystems.com
1-866-793-1542

Customizing Content with DITA Conditional Text and XMetaL

by XMetaL on Jul 14, 2010

Accessibility

Categories

Tags

Upload Details

Usage Rights

Statistics

Customizing Content with DITA Conditional Text and XMetaL — Presentation Transcript