lavacon 2017 - implementing a customer-driven transition to dita content: a step-by-step journey to...

Copyright © Ciena Corporation 2017. All rights reserved. Confidential & Proprietary.

Implementing a Customer-driven Transition to DITA Content

Susanna CarlisiNovember 5, 2017

A Step-by-Step Journey to Success


Transition goals


Background: Why are we doing this?Slide 1 of 2

Issue Key pointsCannot find required information No predictability in the content

• Customers access documentation for multiple products• Each product library created using different standards; no consistency• Large volume of content in several libraries

Don’t know which content to use Customers are frustrated in having to sift through many procedures, in multiple locations, to complete a single task• Each product supports many configurations/hardware, which is reflected in the

procedures• Attempt to support all users resulted in “Spaghetti” content; frustrating for users• UI based procedures: a single procedure includes steps relevant to multiple tasks• Procedures include conceptual, reference and instructional content

Different customers want different types of documentation

Different customers:• Want comprehensive libraries that provide descriptions and tasks for all features/

configurations that the product supports• Want short, customized guide that facilitates getting started quickly

Customers want documentation customized to a specific configuration

• Customers want documentation customized to their configuration


Background: Why are we doing this?Slide 2 of 2

Issue SolutionCannot find required information Improve consistency, content predictability, and

navigation

Don’t know which content to use Improve usability

Different customers want different types of documentation:• Want comprehensive libraries that provide descriptions and

tasks for all features/configurations that the product supports• Want short, customized guide that facilitates getting started

quickly

Provide a variety of documentation options

Customers want documentation customized to a specific configuration

• Provide custom quick start guides• Enable content filtering


Goals: what we’re promising for Ciena documentationSlide 1 of 2

Transition to topic-based authoring to enable all improvements• Improve consistency and content predictability by structuring content

• Enforces all template rules and writing guidelines• All content conforms to the rules automatically• When documentation across products is consistent the customer will know where to look because the content

becomes predictable• Improve navigation by distinctly separating task, concept, and reference information, and organizing the corresponding

topics in a consistent way across product libraries • Once content is clearly separated into task, reference and concept topics, we can present these categories of

information in a consistent way across libraries making it easier to navigate and drill-down to relevant content• Improve usability by prominently focusing on guiding the user to accomplish specific tasks

• Streamline tasks by breaking out supporting conceptual and reference information to separate topics • Use minimalist writing to keep tasks short and tightly focused (complete one job, focused on user goals, not product

functions)• Eliminate “one procedure for all configurations” model• Use structured authoring to separate content from format (semantic authoring)


Goals: what we’re promising for Ciena documentationSlide 2 of 2

Transition to topic-based authoring to enable all improvements• Provide comprehensive guides (as required), on-product documentation, custom quick start guides, and focus on

documenting specific use cases• Write small topics as a library, and draw on different subsets of these to create diverse published materials• Maintain a primary focus on tasks to document use cases• Support the production of PDF, HTML, and ePubs from same source materials

• Enable content filtering by providing “personalized dynamic content” in HTML5 output• Allow users to self-select relevant content using filtering options in HTML5 output


Where is this all leading?Key ambitions that underpin the Ciena solution

• Consistent content

• Pool of topics that can be


How do we move forward?

Structured FM?

DITA?

Custom XML structure?

Budget considerations?

In-house team?

Solution development?

Tools?

Content management?

Learning?

Training the teams?

Engage a consultant?

Attend a conference?


Ciena’s strategy for determining a solution


Working with Structured FrameMakerA shift in our authoring process

DOCUMENT VIEW

STRUCTURE VIEW

ELEMENTCATALOG


Structured FrameMaker is a natural fit for DITASlide 1 of 2

• Supports standard DITA structures out of the box

• Includes many advanced tools to help customize DITA templates to your particular needs

• Publishing DITA content works very much like publishing we’re used to, using FrameMaker to generate PDFs, without the need to build a costly publishing solution

• The same content can be published via FrameMaker as HTML (including Personalized Dynamic HTML5) and ePub

• Structured FrameMaker incorporates powerful publishing tools that make it easy to take a chunk of inert XML and publish it as PDF, HTML, and ePub


Structured FrameMaker is a natural fit for DITASlide 2 of 2

• Structured FrameMaker enforces consistency:

• The Structured FrameMaker interface is very good at guiding (and requiring) authors to create content that conforms to our underlying template. This is enormously important for preventing lots of issues that can arise when processing our files for different uses and types of output.

• Adobe is a positive as well: their resources can help guide us through process hurdles and address issues that we report


DITA: the Darwin Information Typing Architecture

DITA is an XML standard that defines widely recognized topic types and their structures for topic-based writing:

CONCEPT

Title

Short Desc.

Concept Body

Para

Para

List

List Item

List Item

REFERENCE

Title

Short Desc.

Reference Body

Para

Table

Parameter List

Para

TASK

Title

Short Desc.

Prerequisites

Task Body

Step

Step

Step

Result

Example

An industry standard for organizing content into tasks, concepts, and reference topics.

The DITA standard defines the topic types in great detail, defining what is legitimate inside a topic.

Ciena-compliant DITA template is a subset of the out-of-box DITA template FrameMaker provides.


DITA: Sharing and re-using topics in new contextsAmbition for all of our content

ManualCustomer

A

ManualCustomer

B

Reference Guide

Quick Start Guide

DITA is well suited to working from a library of topics to create multiple published deliverables.

Including and excluding topics is a simple way of shaping content for different purposes.

Topics(c, r, t)

Use maps to assemble content


Transition strategy:How do we move from unstructured content to DITA?


High-level steps in the transition to DITA authoringPhased approach

Step 1Strategy

Step 2 Template

development & conversion

Step 3 Metadata/reuse and

FM variable/condition

strategy

Step 4 CCMS

implementation

Today’s focus

Phased approach is more realistic for smaller budgets and teams with limited resources


Conversion phase

ORIGINAL BOOK

CONVERTED BOOK

DITA VERSION OF

EXISTING CONTENT

UPDATEDWITH SOME NEW DITA ELEMENTS

IT’S BETTER, BUT STILL

NOT GREAT

UnstructuredFrameMaker

UPDATED BOOK WITH

REVISED STRUCTURE

NOW THAT’S DITA!

Structured FrameMaker

XML/DITA

1 2 30


XML/DITA


XML/DITA

• Convert content “as-is”, with minimal manipulation of the source content and no restructuring of content.

• Prepare writers by providing training.

• After conversion, add new DITA elements to content, such as Short Description.

• Even Phase 3 will be a hybrid that uses DITA capabilities for most things, but relies on native FrameMaker capabilities for others (such as variables and conditional text).


Training sessions for authors


Conversion procedure


Focus on the conversion procedure

ORIGINAL BOOK

BOOKPREPARED

FOR CONVERSION

CONVERTED BOOK




XML/DITA

Today’s session focuses on: • considerations for converting unstructured FrameMaker content to XML/DITA• the tools FrameMaker provides for converting content• creative solutions for making the conversion as painless and seamless as possible

10


Conversion result: A reproduction of our original content in DITA format

CHAPTER 1 CHAPTER 2

C / FILE

C / FILE

R / FILE

C / FILE

C / FILE

R / FILE

C / FILE

R / FILE

Each procedure is now a separate Task topic.

• Each Task includes all of the same mixed content types as the original procedure.

• As an artifact of the conversion process, some topics will contain other topic elements nested within them.

In a FrameMaker book, each chapter is one file.

After conversion, each topic is its own file, but:

• Separate Concept files will be nested under each other to preserve the original chapter structure

• As an artifact of the conversion process, some topics will contain other topic elements nested within them.


Stages in the conversion process

Stage Description1. Update source content Update your source content to:

• Check and update graphics• Identify topic types• Delete formatting-specific paragraph tags

2. Set up the DITAenvironment

• Point FrameMaker to the DITA structure definitions/authoring templates• Set up custom menus for Ciena workflows (TCE menu)• Point FrameMaker to PDF publishing templates

3. Structure FrameMakercontent and save toXML/DITA

• Merge book into a single file• Convert to Structured FrameMaker and run scripts to prepare content for

XML/DITA• Convert to XML/DITA

4. Chunk file into topics • Run script to split single book FM file to individual topics

Conversion process

Prepare

Update content

Set up environment

Structure

Burst to topics

Conversion package

Demo

Converted content

Validation

Next steps

Questions?

Conversion process

Update contentSet up environmentStructureChunk to topics

Conversion package

A look at converted content


1. Update source content: Update graphics

• Rework composite graphicsComposite graphics are graphics created using the FrameMaker drawing tools. Composite graphics are not supported in XML. Rework composite graphics either by recreating them in a graphics software, or by taking a screen capture of the FrameMaker composite graphic and saving the screen capture as the new graphic.

• Rename graphics filesSpecial characters and spaces are not allowed in filenames. Allowable characters in graphics files are: uppercase and lowercase letters, numbers, hyphen, and the underscore character (no spaces!). Yes, this means you will need to reimport graphics that you have renamed.

• Reimport graphics that have been “Copied into document”Graphics copied into documents are not supported. Ensure graphics are imported by reference.

Conversion process

Prepare

Update content

Set up environment

Structure

Burst to topics

Conversion package

Demo

Converted content

Validation

Next steps

Questions?

Conversion process


Conversion package


• Ensure graphics anchors are at the end of the caption paragraph


1. Update source content: Identify topic types

• For the conversion process to create the correct topic types, you must identify the topic type for each section (h1, h2, variations of h1/h2, and list of terms) in your source FrameMakerdocumentThe default topic type is task, therefore, no changes to headings are required for procedures. For sections that are not tasks, you must identify the topic type by applying new heading paragraph tags.

These new paragraph tags will be included in a preconversion_templatewhich you will import into your source documents

Conversion process


Conversion package



1. Update source content: Delete formatting-specific paragraph tags

• Structured content is semantic. There are few allowances for tagging content for formattingParagraph tags that are used to control page formatting cannot be mapped to DITA.

• Some paragraph tags are not supported because there is no corresponding element in DITA For example, since composite graphics are not supported, there is no need for the paragraph tag that is used for captions in composite graphics.

• As a result of the above statements, many paragraph tags must be removed from the source content. We implemented a script to automatically delete specified paragraph tags from the source content.

Conversion process


Conversion package



2. Set up the DITA environment

• Structure directory: Structured FrameMaker with DITA authoring relies on several templates, XML markup declarations, context rules, authoring templates, read/write rules and stylesheets to define the entire “structure application”.

TCE menu: In addition, we also use custom Ciena tools to enhance the authoring experience. These tools are available in a custom TCE menu added to FrameMaker.

• Maker.ini: The FrameMaker initialization file that defines the FM configuration settings. Includes pointer to the Structure directory.

• PDF publishing templates: Independent from the authoring templates, but can be identical. Stored separately from the authoring templates.

Conversion process

Prepare

Update content

Set up environment

Structure

Burst to topics

Conversion package

Demo

Converted content

Validation

Next steps

Questions?

Conversion process


Conversion package



3. Structure FrameMaker content and save to XML/DITA

• High-level procedure steps- Run scripts, and merge entire book into a single file- Perform a MIF wash- Fix unresolved cross-references that resulted from the book merge- Using a conversion table file, add structure to the merged book file- Run TCE tools to prepare the merged book file for conversion to XML- Save the merged book file to XML

• A conversion table document includes the rules for mapping between paragraph/character styles and DITA elements. The conversion table automates the task of adding structure to documents. Applying the conversion table to a document wraps elements throughout the document all at one time. This is much faster than wrapping text manually in elements.

Conversion process


Conversion package



4. Chunk long XML file into topics

• At this point, the entire book is still contained in just one, huge XML file. In this step, you run a script on that file to break it apart into separate files, one for each topic, all organized within a DITA map.

Output of running the chunk topics script: DITA map created with individual topics chunked at the h1 and h2 levels.

Conversion process


Conversion package



Conversion package

The following tools and folders are provided to support the conversion process.

• Conversion procedure

• Structure directoryWithin the Structure directory, the ConversionTools directory contains:

• Scripts directory that contains the TCE conversion tools

• Conversion table FrameMaker file

Conversion process


Conversion package



Demo



Navigating converted files• Converted books will now be made up of lots and lots of small files; each file is a

single topic, and many topics are tiny.• These are XML files, but they will have the extension “.dita”, and not “.xml”.• These files will have file names like “450-3201-351-i1056712.dita”.• In FrameMaker, the list of files in a DITA Map shows these file names by default;

but you can toggle between displaying that list using file names, or using nav titles.• Specifically, this tree displays the value in the TopicRef’s “Nav Title” attribute.

Conversion process

PrepareUpdate contentSet up environmentStructureChunk to topics

Conversion package




Opening converted files• When you open a file, it may take a while to display. That’s because

FrameMaker runs through every cross-reference in the file and validates each one before displaying the topic in Document View.

• You can disable this checking to speed up the opening of files with many cross-references.

Conversion process


Conversion package




For converted content, the top-level element will always be a generic dita element, capable of containing almost any content.

The next element will always be a Concept, Reference, or Task element. When writing new content, this will always be the top-level element.

The title element follows. Every topic has a title.

The conbody element follows (at least, for a Concept topic). This is the container for all of the content that forms the meat of the topic.

Right here, after the title but before the conbody, is where the Short Description belongs. We will be adding these short descriptions ourselves, later. There was no way to create or deduce a short description’s content during conversion.

The outputclass attribute for each element records the paragraph style of the original content before conversion.

Conversion process


Conversion package




The conversion process will sometimes create more than one Task topic within the same DITA container: this “nested” format will allow you to retain conceptual information in the task until you are ready to rework your content.

Conversion process


Conversion package



A look at converted content: Front and back matter

The DITA map includes none of the following:• front cover• table of contents• Index• back cover

• These book elements are managed differently when publishing DITA with FrameMaker.

• FrameMaker uses a single master set of these documents that it uses any time you publish .

• You can set variables and conditions for each document to control what information appears each time you publish with those master documents.

Conversion process


Conversion package



and

Conditions

A look at converted content: Front and back matter

Front Cover

TOC

Index

Back Cover

Variables

PDF

Conversion process


Conversion package



Q & A

lavacon 2017 - implementing a customer-driven transition to dita content: a step-by-step journey to...

Technology