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 PDFpage layouts


Typical bookmap – a map of the chapter maps


“Building the book” results in a set of SFMfiles corresponding toeach of the chaptermaps from the main bookmap…


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


“Raw” SFM – H1 at top is supposedto be the “chapter start” page…

…so you have to manually assignthe correct page layout


Chapter start page and orphans in the right places…


Plug-in Example: StructureSnippets

Note element inDITA source file


Plug-in Example: StructureSnippets

Note element inDITA 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 DITAtopics & 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

[email protected]

…Thanks for attending!

DITA Proof-of-Concept Publishing System

Technology

Transcript of DITA Proof-of-Concept Publishing System