DITA Proof-of-Concept Publishing System
-
Upload
matso-limtiaco -
Category
Technology
-
view
457 -
download
5
description
Transcript of DITA Proof-of-Concept Publishing System
1COMPANY CONFIDENTIAL
DITA Proof-of-Concept Publishing System
Matso Limtiaco, Principal Technical Writer
Intermec Technologies Corporation
Everett WA
2COMPANY CONFIDENTIAL
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
3COMPANY CONFIDENTIAL
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”
4COMPANY CONFIDENTIAL
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
5COMPANY CONFIDENTIAL
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
6COMPANY CONFIDENTIAL
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
7COMPANY CONFIDENTIAL
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…
8COMPANY CONFIDENTIAL
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
9COMPANY CONFIDENTIAL
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
10COMPANY CONFIDENTIAL
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?
11COMPANY CONFIDENTIAL
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…
12COMPANY CONFIDENTIAL
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…
13COMPANY CONFIDENTIAL
SFM example…
Element tags “off” Element tags “on”
14COMPANY CONFIDENTIAL
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)
15COMPANY CONFIDENTIAL
Sandbox Examples
Practice concept topic
16COMPANY CONFIDENTIAL
Sandbox Examples
Practice task topic – tags turned off
17COMPANY CONFIDENTIAL
Sandbox Examples
Practice reference topic
18COMPANY CONFIDENTIAL
Sandbox Examples
Practice DITA map
19COMPANY CONFIDENTIAL
Sandbox Examples
“Generate Book from Map…”
20COMPANY CONFIDENTIAL
Sandbox Examples
“Generate Book from Map…”
21COMPANY CONFIDENTIAL
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
22COMPANY CONFIDENTIAL
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…
23COMPANY CONFIDENTIAL
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
24COMPANY CONFIDENTIAL
DITA Server Structure: Relative to the map location, flatter is better…
25COMPANY CONFIDENTIAL
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
26COMPANY CONFIDENTIAL
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
27COMPANY CONFIDENTIAL
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
28COMPANY CONFIDENTIAL
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…
29COMPANY CONFIDENTIAL
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!
30COMPANY CONFIDENTIAL
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!
31COMPANY CONFIDENTIAL
Concept Topic with Element Tags …and without Element Tags
32COMPANY CONFIDENTIAL
Task topic Reference topic
33COMPANY CONFIDENTIAL
Concepts Tasks References
34COMPANY CONFIDENTIAL
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
35COMPANY CONFIDENTIAL
Typical bookmap – a map of the chapter maps
36COMPANY CONFIDENTIAL
“Building the book” results in a set of SFMfiles corresponding toeach of the chaptermaps from the main bookmap…
37COMPANY CONFIDENTIAL
“Raw” SFM files – no page layout tweaks yet…
38COMPANY CONFIDENTIAL
39COMPANY CONFIDENTIAL
40COMPANY CONFIDENTIAL
“Raw” SFM – H1 at top is supposedto be the “chapter start” page…
…so you have to manually assignthe correct page layout
41COMPANY CONFIDENTIAL
Chapter start page and orphans in the right places…
42COMPANY CONFIDENTIAL
Plug-in Example: StructureSnippets
Note element inDITA source file
43COMPANY CONFIDENTIAL
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:
44COMPANY CONFIDENTIAL
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...
45COMPANY CONFIDENTIAL
Fixing columns in Russian?...
Raw SFM Edited SFM
46COMPANY CONFIDENTIAL
Non-DITA FM files – created in the standard way from existing templates
SFM files from DITAtopics & maps
The Finished Book…
47COMPANY CONFIDENTIAL
Reusing bookmaps for translated docs
Directory structure is identical for all languages – we can use the same maps for all versions of the document
48COMPANY CONFIDENTIAL
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
49COMPANY CONFIDENTIAL
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…)
50COMPANY CONFIDENTIAL
Information Model Examples
51COMPANY CONFIDENTIAL
Information Model Examples
52COMPANY CONFIDENTIAL
DITA Notebook Examples
53COMPANY CONFIDENTIAL
DITA Notebook Examples
54COMPANY CONFIDENTIAL
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:
55COMPANY CONFIDENTIAL
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…
56COMPANY CONFIDENTIAL
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!
57COMPANY CONFIDENTIAL
Questions?
My contact info:
Matso Limtiaco
425-265-2383
…Thanks for attending!