DITA Proof-of-Concept Publishing System

1COMPANY CONFIDENTIAL
DITA Proof-of-Concept Publishing System
Matso Limtiaco, Principal Technical Writer
Intermec Technologies Corporation
Everett WA

What you will learn today
 How we built a DITA-based publishing process with a small staff
and small (non-zero) budget
You should already know…
 what DITA is
 the general concepts of “structured authoring”
What you won’t learn from me today…
 Basic DITA authoring, except as part of the story
 Fancy DITA publishing tricks – our DITA implementation is simple
 Advantages of one software tool over others…we’re FrameMaker-
centric here

A few words on DITA…
“Darwin Information Typing Architecture” – an XML standard specific to
technical writing
 All content in concept, task, and reference topics
 Pieces of content within a topic are wrapped in structure tags (as
opposed to semantic markup, like H1, Body, etc.)
 Every topic is standalone – needs no other topic to function as a
complete chunk of information
 No “go-to” software tool for DITA authoring
 Processes make some easy stuff hard
 Industry hasn’t embraced DITA as the future of writing
 “It isn’t easy, it’s efficient”

A few words on Intermec…
Makers of supply-chain data collection hardware and software
 Bar code readers
 Mobile computers with bar code scanners, smartphone capability
 Bar code label printers and print media
 RFID readers and tags
 APIs and applications
Several US locations, Singapore, field offices

A few words on Intermec Tech Comm…
Small staff: Manager, 6 writers
 One junior writer with DITA background (in 2009)
Mature processes and tools
 The usual deliverables…
 Template-based, task-oriented writing
 Tools: FrameMaker, InDesign, Robohelp
 Deliverables: Print, PDF, online Help

Our DITA Publishing System is a process for creating
product user manuals using DITA topic-based
authoring.
System uses existing tools
 Structured FrameMaker 8
 Plug-ins – DITA-FMx, StructureSnippets
Limited output: PDF only
Limited resources
 No DITA-specific staff – we have our “day jobs” too
 < $5000/year for training
 Software purchases every other year
 No CMS or IT support

Manuals Published:
2012:
 PC23 and PC43 Desktop Printer User Manual
 Manual del usuario de la impresora de escritorio PC23 y PC43
 Bedienungsanleitung der Desktop-Drucker PC23 und PC43
 PC23 和 PC43 桌面型打印机用户手册
 Manual do Usuário das Impressoras de Mesa PC23 e PC43
 PC23 和 PC43 桌上型印表機使用者手冊
 PC23 및 PC43 데스크톱 프린터 사용 설명서
 Руководство пользователя настольных принтеров PC23 и PC43
 Manuel d’utilisation des imprimantes de bureau PC23 et PC43
 Stampanti desktop PC23 e PC43 – Manuale dell’utente
 PM43 and PM43c Mid-Range Printer User Manual
 PM43-und PM43c-Mittelbereichsdrucker Bedienungsanleitung
 PM43 y PM43c impresora de nivel intermedio Manual del usuario
 PM43 et PM43c Imprimante de milieu de gamme Manuel d’utilisation
 PM43 e PM43c Stampante di fascia media Manuele dell’utente
 PM43 및 PM43c 중간 범위 프린터사용 설명서
 PM43 e PM43c Impressora Média Manual do usuário
 PM43 и PM43c Принтер средних размеров Руководство
пользователя
 PM43 和 PM43c 中端打印机用户手册
 PM43 和 PM43c 中間範圍印表機使用手冊
2012 (continued):
 PR2 and PR3 Mobile Receipt Printer User Manual
 PR2 和 PR3 移动收据打印机用户手册
 PR2 和 PR3 行動收據印表機使用手冊
 Manuel d’utilisation des imprimantes mobiles de
reçus PR2 et PR3
 Mobilbelegdrucker PR2 und PR3 –
Bedienungsanleitung
 Manuale dell’utente delle stampanti portatili di
scontrini PR2 e PR3
 PR2 및 PR3 모바일 영수증 프린터 사용 설명서
 Manual do Usuário da Impressora Móvel de Recibos
PR2 e PR3
 Руководство пользователя мобильного
принтера для чеков PR2 и PR3
 Manual de usuario de la impresora móvil para
recibos PR2 y PR3
 CK3R and CK3X Mobile Computer User Manual
 2nd revision, PC23 and PC43 Desktop Printer User
Manual (all languages)
2013 (Pending):
 Two more computer user manuals…

What does the publishing system cost?
Item Date $
Structured FM training, plus SFM DITA custom files 2009 4500
DITA-FMx software 2009 1500
Information Modeling workshop 2011 1400
StructureSnippets software 2011 300
TOTAL 2009 - present 7700

Why did we decide to try DITA authoring?
Mid-2009: Dept. wanted to learn more about DITA topic-based
authoring – possibly create a proof-of-concept manual…
Around the same time, Marketing announced a new line of bar code
label printers…
 Printers would use
common, proprietary
firmware
 10 languages requested
for user manuals
 Product release date:
Mid-2011

The Perfect Proof-of-Concept?
Good reasons for using DITA authoring:
 Shared firmware: Reusable content?
 Nine translations for user manuals: DITA topics can save
translation costs
 Release date: 20+ months – Plenty of time to learn?
 Structured FrameMaker can handle DITA authoring – No need
for new tools?

Brief Timeline
2010
 Dept. moved into Structured FM
2011
 R & D of publishing methods, DITA authoring concepts
 Authoring of first manual built from DITA topics
2012
• Three manuals completed (July: First doc with multiple authors)
• September: First revisions to original document
2013
• Two more manuals underway…

2010: Moving to Structured FM
Consultant provided one-day workshop, DITA structure applications
 Dept. goal: Learn the terminology and basic processes of structured
authoring
Two writers attended minimalism classes
After a year, most of department was familiar with structured authoring
concepts
 Two writers completed 150+ page user manuals in SFM
 Others: smaller documents, some single topics based on legacy
content
Printer schedule: 6 month slip – now due end of 2011…

SFM example…
Element tags “off” Element tags “on”

2011: Moving towards DITA authoring…
When we started to write DITA topics, we discovered that SFM authoring
isn’t exactly the same – we needed to learn more…
 How do you write a <shortdesc>?
 What kind of metadata do we want to include?
 What should we name our topic files?
 Where should we store topic files?
Comtech workshop scheduled for mid-year
The new Project Engineer…
 No more technical help?
 How to learn what this is supposed to do? Playing in the Sandbox:
“How-to” procedures for publishing (but not authoring)

Sandbox Examples
Practice concept topic

Sandbox Examples
Practice task topic –
tags turned off

Sandbox Examples
Practice reference topic

Sandbox Examples
Practice DITA map

Sandbox Examples
“Generate Book from Map…”

Mid-2011: DITA authoring begins…
May: Information Modeling workshop
 Information Model: “A framework for categorizing and organizing
content so it can be delivered and reused in a variety of ways”
 Starting point for authoring: Lists the base DITA elements you plan
to use and defines how to determine and organize content into
concept, task, and reference topics

Mid-2011: DITA authoring begins…
May: Information Modeling workshop
 Information Model: “A framework for categorizing and organizing
content so it can be delivered and reused in a variety of ways”
 Starting point for authoring: Lists the base DITA elements you plan
to use and defines how to determine and organize content into
concept, task, and reference topics
Workshop gives us a better idea of what to do with content…
 Principal writer begins work on Information Model
 “How-to” procedures become the “DITA Notebook”
 Between the Model and Notebook, our own best practices start to
emerge…

Examples – Basic Authoring Conventions
File naming conventions
 Concepts: “About…” or “How To…”
 Tasks: Action verbs – “Configure…,” “Install…,” “Connect…”
 References: Noun phrases – “Wi-Fi Settings,” “Printer Accessories”
 Maps: Keyed to product, doctype, chapter – “PC43UM_CH01”
DITA Server organization
 Language
 Product type
 Product model number
 Concept, task, reference, graphics directories

DITA Server Structure: Relative to the map location, flatter is better…

Summer 2011: DITA authoring continues…
Authoring new content was easier than expected
 Each feature generally needed one concept topic and multiple task
topics, with reference topics as needed for “speeds and feeds”
 Information Model revised as we discovered more or fewer needs
Documents published to PDF for reviews
 Used existing review process (no difference to SMEs)
Project Engineer: Continuous R & D (and authoring!)
 Trying to automate publishing tasks: language-specific templates,
DITAVAL files to hide content
 More publishing procedures for the DITA Notebook

Late 2011: Translating the manuals…
After English version approved, sent .zip of all topics to translation
vendor
 Translated topics have English file names, xml:lang attribute
 Why not send complete manual to vendor? Page layout fees…
Used EN bookmaps to generate FM files from translated topics
 FM files needed lots of page layout work

2012: Using the system…
March:
 Released the first manuals!
 Third writer started authoring topics, created a “best practices”
authoring handbook
June:
 All three manuals done!
 “Noobs” did page layout work for vacationing writer
July – Sept.:
 Started new computer user manual – first doc with multiple authors
 Revisions to first manual: three new topics, three revised topics

Did we really save money on translations?
Full user manual
 Estimated: $6K/language (2009, includes DTP fees)
 Actual: <$5K/language (2011, no DTP fees)
Revisions (nine languages)
 Estimated: $5K total
 Actual: $2K
Most of the savings were (and will continue to be) in sustaining work…

How about shared content?
Printer manuals
 Shared content guesstimate: 30% of all topics
 Actual shared content: 20% of all topics
Computer manual
 Shared topics with new computer user manual:
70% (with tags, @product as needed)
…that’s 106 topics I don’t have to write!

The Process
1. Author topics in SFM.
2. Create DITA maps. Each map = single chapter in finished book.
3. Generate FM files (“build a book”) from the maps.
4. Publish to PDF for reviews.
5. Revise, publish, review again.
6. Generate final FM files and perform final page edits.
7. Publish to PDF, perform dept. QC.
8. Send all topics (NOT completed EN book) for translation.
9. Repeat 6-7 for each language.
10. Release the manuals!
… On to the examples!

Concept Topic with Element Tags …and without Element Tags

Task topic Reference topic

Concepts Tasks References

Typical DITA map
 Content of one map =
one chapter in the book
 First topic in map is
“chapter start” topic –
used only for PDF
page layouts

Typical bookmap – a map of the chapter maps

“Building the book”
results in a set of SFM
files corresponding to
each of the chapter
maps from the main
bookmap…

“Raw” SFM files – no page layout tweaks yet…

“Raw” SFM – H1 at top is supposed
to be the “chapter start” page…
…so you have to manually assign
the correct page layout

Chapter start page and orphans
in the right places…

Plug-in Example: StructureSnippets
Note element in
DITA source file

Plug-in Example: StructureSnippets
Note element in
DITA source file
Note element in
generated SFM
At book build time, SFM calls StructureSnippets to move all Note elements
into a formatted table with graphic, like this:

In our setup, SFM doesn’t recognize
when a table column is too wide or
not wide enough… …so there’s a lot of table editing.
 Probably a way to make this happen automagically...

Fixing columns in Russian?...
Raw SFM Edited SFM

Non-DITA FM files – created in the standard way from existing templates
SFM files from DITA
topics & maps
The Finished Book…

Reusing bookmaps for translated docs
Directory structure is identical for all languages – we can use the same
maps for all versions of the document

Managing the Publishing System
DITA implementations often result in new roles for team members:
 Information architect, Information developer, Information-
development manager, Production manager
(from CIDM Information Management News, 12/2005: The Effect of DITA on
Information-Development Roles)
With a small team, we simplified the titles and share the
responsibilities…so we have:
 Project Manager
 Project Engineer

Project Manager
 Creates and maintains the Information Model
 Trains all writers in DITA authoring
 Sets project deadlines
 Makes recommendations to Dept. Manager
Project Engineer
 Creates and maintains the DITA Notebook
 Maintains and distributes the “engine files”: structure applications,
“snippet” files, language-specific templates
 No XSL coding (yet…)

Information Model Examples

DITA Notebook Examples

concept, conbody fig, image
task, taskbody info
reference, refbody note
shortdesc menucascade, uicontrol
title context
p, section userinput
table steps, step, cmd
ul, ol, li
 Metadata: @product, @platform
 Use to exclude stuff from the output (per Dave Gash)
How much DITA do you need to know?
 DITA Specification defines 170+ elements…but we mostly use just these:

Where we’re going next…
 More content reusability (conrefs)
 More output types (HTML prototype)
 Maybe new tools (oXygen? CCMS?)
…but budget remains (non-zero) small…
 Only a few new manuals on the 6-9 month horizon, so a great time
for more R & D…

Hints from the Project Engineer…
 No spaces in filenames
 Write everything down!
 Keep your pilot project simple
 IMO, publishing is the tricky part
 Why not DITA-OT?
 Allow plenty of time for page layout tasks (no DITA chops required)
 DITA authoring is easier than you think…
 Socio-political implications?
 Authors unwilling to embrace change?
 Use DITA if it helps you create stuff your customers want!

Questions?
My contact info:
Matso Limtiaco
425-265-2383
matso.limtiaco@intermec.com
…Thanks for attending!

DITA Proof-of-Concept Publishing System

Recommended

Recommended

More Related Content

Similar to DITA Proof-of-Concept Publishing System

Similar to DITA Proof-of-Concept Publishing System (20)

Recently uploaded

Recently uploaded (20)

DITA Proof-of-Concept Publishing System