Going the DITA way

10/16/2013 © 2013 IBM Corporation
Going the way . . .
Abigail Samuel and Alka Acharya
Information Developers @ IBM

Going the DITA way . . .
2 © 2013 IBM Corporation

Problems with legacy documentation model

Book paradigm

Linear flow

Bulky, difficult to manage

Information duplication

…

In short, problems for end users as well as the documentation teams.

Legacy documentation at IBM

A document markup language based on Standard Generalized Markup Language (SGML).

The legacy documentation followed the book paradigm.

IBM invented DITA

Developed the information typing strategy

Implemented the strategy by using XML and was named DITA!

DITA – As we know it
Darwin
Information
Typing
Architecture

The DITA solution

Create, manage, and publish XML-based information

Topic-oriented paradigm

Flexible content structuring

Facilitate reuseEclipse ArchitectureMapBuildMapsTopicsOutputsEclipse helpJavaHelpHTMLHelpWeb pagesBooks & PDFsLearningWriteBuildArchitectInformation ArchitectureMapBuildMapsTopicsOutputsWriteBuildArchitectInformation ArchitectureMapBuildMapsTopicsOutputs

DITA – As we experienced it
Dynamic
Influential
Trendsetter
Adaptive

Interesting Read!
Source: http://www.ditawriter.com/so-whos-using-dita-january-2013-update 2

Adopting DITA
Conceptualize and decide
–
Create a business case and justifications, proof of concept (POC)
–
Thought leaders get the buy-in from top management

Moving to DITA
Initiate the change
1.
Investigate tools and processes
2.
Launch pilot project
3.
Define the migration strategy
4.
Announce, demo, educate, advocate, and support
DITA OT – HTML to DITA
Mif2Go
Adobe FrameMaker Conversion Tables
Stilo Migrate
Proprietary tools
…

Our need for migration

Some of the existing legacy information sets of our projects were still in the SGML based format

Corporate directive, deadlines set

The DITA migration process
ASSESS
DECIDE
PROTOTYPE
PLAN
TRAIN
EXECUTE
MONITOR

Assess legacy content

INFORMATION UNIT It could be any modular unit of information, but in the context of this presentation, we refer to it as piece of information that can be completed end-to- end, translated, and published as a unit without other dependencies.

Use a consistent metric throughout for sizing

Online documentation Downloadable PDFs Context-sensitive help Embedded help Technical notes . . .

Other documentation Error messages Code, Javadocs, MAN pages Other departments . . .

Other departments or products that might have dependencies on this documentation set

All legacy content? Only certain kinds of information? Only content that will continue to be updated in the future?
Examples: GUI-based installation steps will change entirely Support discontinued for ABC operating system

Analyze state of content specifically from a DITA point-of-view

How structured is the legacy content?
Is it organized into topics already?
How easy would it be to fit into the concept, reference, and task DITA topic types?
Unstructured:
Linear, book-type
Partially structured:
Relatively easy to restructure into DITA topics
Structured:
Entirely topic-based, but does not conform to DITA

Consistency makes it easier to run scripts and search and replace.
Example: Bold and italic highlighting is not used consistently for command names, variables, etc.

Common information repeating across information units: Product names Operating system names Version numbers Standard product description Legal notices
Entire documentation sets duplicated with only few differences

Short description
Minimalism
Latest style guidelines
. . .

Decide on the approaches

Convert in-house
–
Availability of development teams to answer queries
–
Lack of budgets to outsource or hire consultants

Outsource
–
Vendors who specialize in DITA migration and have the tools
–
Lack of time and resources to convert in-house

Decide on the approaches

Clean up legacy information and then convert

Convert to DITA and then clean up

Create a prototype

Select varied content types

List each step in the process

Record time spent on each step

Disclaimer:

This list does not contain all the steps; it is only a small snippet of our really long task list.

This is just an example of how to create a worksheet that:

Lists the steps in a sequence

Records time taken per step for a pre-determined unit

Notes the outcome or expected result of each step against which it should be measured upon completion

The estimates are also only examples, they are not ballpark or benchmark figures that you can use or quote.

Create guidelines

Linking and cross-referencing

Writing titles and short descriptions

Highlighting with semantic tags

Using graphics and screenshots

Adding metadata

Navigation structure

File naming and directory structure conventions

Common reusable content

Single-sourcing strategy

Create checklists

Use the process document created during the prototype as a checklist

Plan

Effort estimations

Work assignments

Timelines

Contacts

Summary or dashboard
–
Scope
–
Risks and assumptions
–
Resource requirements
–
Translation requirements

Training and workshops

Refresher
–
DITA
–
Structured authoring principles
–
Authoring tools

Training
–
Conversion process
–
Conversion tools
–
Prototype demo
–
Guidelines and checklists

Execute

Phased approach
–
DITA conversion accomplished fast
–
Avoid neither here nor there situation
–
DITA exploitation can be done at a slower pace
–
Example: End of marketing products

Execute

Phase 1
–
Pre-conversion tasks
–
Only those that are absolutely essential
1

Execute

Phase 2
–
Convert to DITA
1
2

Execute

Phase 3
–
Cleanup just enough to eliminate errors
2
1
3

1
2
3
Execute

Phase 4
–
Generate output
–
Resolve errors
–
Compare with pre-conversion output
4

Execute

Phase 5
–
Comply with DITA model
–
Use the essential DITA features
4
3
2
1
5

5
Execute

Phase 6
–
Incorporate other DITA features
–
Enhance information
–
Requires editorial and technical reviews
4
3
2
1
6

Monitor progress

Dynamic status reports

Overall progress on dashboard

Periodic quality checks of samples

Issues resolved
–
FAQs to maintain consistency
6
5
4
3
2
1

Tips

Migration strategy

In-house migration

Outsourced migration

Pilot project

Mixed/combination topic type

<topicgroup> element

Task topic type

DITA cleanup

Automation

Migration strategy

Choose a phased approach to migration for information sets of products that are in maintenance mode.

Choose end-to-end migration for information sets of live products.

Assign work in an assembly-line approach.

Do not aim to migrate your legacy information set and release the product in the same release cycle.

In-house migration

Specify the skill levels required for each role to ensure the right resources are assigned to the project.

Garner extra resources, if possible. Work with management to advertise the migration activity as a stretch assignment or with a promise of awards for contributing.

Consider getting at least a consultant (within the organization or outside) who specializes in DITA conversion projects to help with the planning and architecture.

Outsourced migration

Establish what the content should look like after conversion (outcome) clearly.

Evaluate results of a pilot before handing over all content for conversion.

Create a single point of contact to co-ordinate the deliverables and schedules with the outsourcing company.

Pilot project

Do not try to convert 10,000 pages/topics in the first go.

Choose the information set that covers all or most of the different facets of your legacy information because this pilot conversion will help you estimate the required effort for subsequent conversions.

Mixed/combination topic type

Avoid using the mixed/combination topic type with which you can mix content from the different topic types.

Use this topic type for all your common or reusable content.

<topicgroup> element

Be careful when using <topicgroup> element as a container topic because it can create empty pages in the PDF and empty topics in the HTML outputs.

If your guide is structured as “Part > Chapter > Topics”, avoid migration of Parts to <topicgroup> and use concept topics as containers.

Task topic type

If you have steps nested by more than two levels, break the steps into several tasks or rewrite the task to avoid nesting steps to more than two levels.

Estimate more efforts on post-migration cleanup activity of task topics as compared to other topic types.

DITA cleanup

Strive to have one topic = one file.

Delete unnecessary links. For example, if you created lists of links as a way to introduce subsections, you should delete those links or that topic altogether. If you don’t remove the links, you could get duplicate links.

Delete unnecessary topics. For example, topics that just introduce a chapter or section in your legacy information set – “This chapter ….”.

Automation

Use scripts and tools as far as possible.

Befriend developers – get their help to write simple scripts.

Examples of how we used Perl scripts:
–
Pre-conversion:
•
Inserted class attribute in division tags with the value that we specified: task, reference, concept. This was later used to split information into topics.
•
Inserted id attribute in division tags which later were used for the topic ID, file name, and cross-references to the topic
•
Moved steps out of paragraph tags
–
Post conversion:
•
Renamed files using the topic IDs
•
Checked whether <shortdesc> tags are empty
•
Inserted <navtitles>

Examples

Legacy info set - snippet

Examples

Pre-conversion tasks

Examples

Converted output where basic pre- conversion cleanup was not done properly

Examples

Migrated DITA topic after post-conversion cleanup

Questions?
You can contact us @ abisamuel@in.ibm.com & alachary@in.ibm.com

Going the DITA way

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Going the DITA way

Similar to Going the DITA way (20)

Recently uploaded

Recently uploaded (20)

Going the DITA way