passport to dita implementation cidm april 2017

29
May 2017

Upload: ixiasoft

Post on 21-Jan-2018

85 views

Category:

Software


1 download

TRANSCRIPT

Page 1: Passport to DITA Implementation CIDM April 2017

May 2017

Page 2: Passport to DITA Implementation CIDM April 2017

About the Speaker

• 18 years in the tech comm domain• Based in Vancouver, Canada• Now in the Pre-sales team for Ixiasoft• [email protected]

Photo by Jerry Meaden. This work is licensed under a Creative Commons Attribution 2.0 License.

Page 3: Passport to DITA Implementation CIDM April 2017

Now Voyager

Page 4: Passport to DITA Implementation CIDM April 2017

Travel Light

• Get rid of the baggage - follow the principles of minimalism

• Select a cut over point:§ Just the latest release§ One or two products only§ One content type§ Run a Pilot

Page 5: Passport to DITA Implementation CIDM April 2017

Identify Objectives

• Prepare for migration?• Improve quality and

consistency?• Find reuse efficiencies?• Minimalize content?

Page 6: Passport to DITA Implementation CIDM April 2017

Look for Patterns

• Find the biggest bucket - start with your largest category of documents

• Subsections (submaps)• Topics• Elements

Page 7: Passport to DITA Implementation CIDM April 2017

Not Always About the Tools

• Genericize – use general terminology• Isolate• Normalize content – look for differences which

are cosmetic or author preferences:

• Decide not to reuse

Page 8: Passport to DITA Implementation CIDM April 2017

Automated or Manual?

Analysis Scripting effort Payback?

Page 9: Passport to DITA Implementation CIDM April 2017

Identify Blockers, Fail, Iterate

• Mixed information types• Invalid DITA content • Mix of formatting and styles• Deeply nested hierarchies• Hard-to-identify topic types

Page 10: Passport to DITA Implementation CIDM April 2017

Home or Away?

• One-time migration tasks– do where it is easiest

• Tasks with learning potential – treat as on-the-job training

• BUT – keep the source close to the original so you can easily do quick QA on the migrated content

Page 11: Passport to DITA Implementation CIDM April 2017

Case Study #1: Analysing Content for Efficient Migration

Page 12: Passport to DITA Implementation CIDM April 2017

- Seven Install Guides - Three install workflows- Install routines for common components for each product

Page 13: Passport to DITA Implementation CIDM April 2017

Installation Instruction (bookmap)

Chapters provide a consistent hierarchy for each workflow and support usability/navigation.

.

Bookmaps reside in the product release version and pull shared content in submaps/topics from library release versions

Submaps organize reused topics. Collections of topics are shared across installation bookmaps, topics are added, removed, or revised once and updated everywhere.

Submaps for install workflows 2 and 3 reuse subsets of same topics from first workflow.

RelTable resides in the bookmapfor inter-topic linking.

IntroductionOverviewRelated Information (reused topic)

General Prerequisites (reused chapter topic)First Install WorkflowDB Prerequisites (submap)

maprefTopicrefTopicrefTopicref

Application Prereqs (app-specific submap)mapref

TopicrefTopicrefTopicref

Component Prereqsmapref

TopicrefTopicrefTopicref

Workflow2 and 3DB Prerequisites

maprefTopicrefTopicref

Unique installation content is included in the bookmap, in its own app-specific submap.

Single reusable topics are referenced by each bookmap and revised once, updated everywhere.

.

Page 14: Passport to DITA Implementation CIDM April 2017

Content Analysis to Reduce Migration Effort

1. Identify topics and topic groups (submaps) that could be reused in the future CCMS environment

2. Document the content model3. Pre-fabricate submaps in the CCMS4. Migrate only unique content5. Drag reused submaps/topics into the right location in

the seven target guides

Only the unique content was prepped, imported, and cleaned up, with massive time savings

Page 15: Passport to DITA Implementation CIDM April 2017

• Reusing submaps represents a significant reduction in maintenance effort.

• When you add or remove a topic, change is propagated across all guides.

• Once we normalized content and genericized terms, reuse of the entire submap is blocked by just one table.

• You can manage unique content in several ways – profile, conref, or keys.

Find Reusable Content Flows (Submaps)

Page 16: Passport to DITA Implementation CIDM April 2017

Use Conditions to Manage Unique Content in Shared Submaps

• Topics which block reuse in a submap can be conditionalized

• All bookmaps referencing the submap update automatically

Page 17: Passport to DITA Implementation CIDM April 2017

Use Keys to Manage Unique Content in Shared TopicsKey maps define how the keys are to be resolved in a given bookmap.

Keymap referencing two keys

• keys—Human-readable name that applies to both keys in the set (in this example, “install_cudb”). The same for each keydef regardless of product.

• keyref—ID of the key (referable-content object). Each keydef points to a different object.

Each keydef is addressed as follows:

Page 18: Passport to DITA Implementation CIDM April 2017

Case Study #2: Analysing Content for Reuse

Page 19: Passport to DITA Implementation CIDM April 2017

Reusing Topics - Strategies• Genericize: Is it possible to remove details such as

product specifics without affecting usability? • Isolate: Is it possible to isolate diverging content in

a specific document, map title, topic title?• Normalize: Is the content similar enough that you

could rewrite it to be identical?• Separate: Can you separate diverging content into

blocks and conditionalize and generate different flavors of a document (one for product A, one for product B)?

Page 20: Passport to DITA Implementation CIDM April 2017

• Example 2: Change all variant titles to Create and Configure the LDAP User

Remove Application-specific TermsMaximize reuse with generic references:

Disconnect all electrical connections from the ABC board

Disconnect all electrical connections from the XYZ board

• Create and Configure LHR LDAP User

• Create and Configure AME/PG LDAP User

• RIE LDAP User• AME/PG LDAP User

• Example 1: Refer generically to “the board”? (doc title identifies the product).

Page 21: Passport to DITA Implementation CIDM April 2017

Normalize Diverging Content

• Every instance must be updated, multiplying effort exponentially.

• Graphics also may have diverged.

• Creates a usability issue for the user.

• Creates an issue for the writer – which one is correct?

Initialize the System1. Initialize the system by clicking Diagnostics > System> Initialize.

Initialize the XYZ System1. Go to Diagnostics.2. Select System.3. Choose Initialize from the drop-down menu4. Click Go.5. Wait for the initialization to complete.

Page 22: Passport to DITA Implementation CIDM April 2017

Postcard From the Other Side

Page 23: Passport to DITA Implementation CIDM April 2017

Manage Identical Headings

• In a CCMS, topics are stand-alone

• Duplicated titles make rapid retrieval harder

• Disambiguate headings– one possible strategy

Page 24: Passport to DITA Implementation CIDM April 2017

Review Stacked Empty Headings

• Blank headings can be useful to create a hierarchy or enforce consistency

• Consider how this works in a topic-based content model

Page 25: Passport to DITA Implementation CIDM April 2017

Develop a Strategy for Managing Images

Page 26: Passport to DITA Implementation CIDM April 2017

Reusing Elements

• Notes and Warnings• Definitions• Steps• Store in maps for

easy management, review and retrieval

• Conref these single instances into multiple topics

Page 27: Passport to DITA Implementation CIDM April 2017

Inline Elements

• Inline tagging:§ Improves consistency and usability§ Save effort – writer doesn’t have to think about each

button or dialog box• Tagging is semantic, not about formatting• If inline tagging is inconsistent, it will migrate

inconsistently• Use the minimal amount of inline tagging

Page 28: Passport to DITA Implementation CIDM April 2017

It’s Not Going to Be Perfect, But It Will Be Interesting• Keep analysing your content and looking for new

opportunities• Go for the biggest chunks of reuse because that’s

where you will find the biggest payback• Content structure is harder to change than

retrofitting notes into conrefs• Doing the little pieces before the big ones can

sometimes lead to rework• Sometimes you need an outside perspective

Page 29: Passport to DITA Implementation CIDM April 2017

Questions