Cheaper, Faster, Better DITA Implementations, Part 2

Prepared by © 2009 Lasselle-Ramsay

Presented by

Secrets to Cheaper, Faster and Better DITA Implementations

Part 2

Secrets to Cheaper, Faster and Better DITA Implementations

Part 2Presenter from Lasselle-Ramsay

Tom Voltz

Welcome!Welcome!

• Today’s event is being recorded – link available in follow-up email

• Use Q&A panel to submit questions for Q&A session• Full screen view available for slides

Our PresentersOur Presenters

Joan LassellePresident

Tom VoltzTechnology Consultant

Lasselle-Ramsay Industry ExpertiseLasselle-Ramsay Industry Expertise

27 years supporting Fortune 100 clients with their content infrastructure

Overview for TodayOverview for Today

• Part I Review• Sample Documentation Set• Specialization Best Practices

Poll – Part IPoll – Part I

Question: Were you able to watch the first part of this webinar?

Yes No

Part I ReviewPart I Review

DITA – Out of the Box DITA – Specialized

• Fundamental DITA Open Toolkit architectural feature:

Myth BustingMyth Busting

EffortEffort

Mary

Joe

Units of Labor

Content Analysis

Training Development

Training Delivery

Specialization

Sample Documentation SetSample Documentation Set

• 7 Product Variations• User Manual• Context Sensitive Online Help

Lasselle-Ramsay Six-Point ApproachLasselle-Ramsay Six-Point Approach

Define User ExperienceDefine User Experience

• Develop Personas– Representative

customers

• Task Analysis– Lifecycle of product

from customer perspective

– Specific tasks, connected to personas

Finding: Distinct AudiencesFinding: Distinct Audiences

• Jake – End User – Manual to big, not useful

– Context sensitive help too brief, frustrating

• Sam – Field Service Technician – Insufficient detail

– Can’t lookup error codes quickly

– Procedures are confusing (inconsistent with user interface)

Analyze WorkflowAnalyze Workflow

• Map of current content lifecycle• Alignment of other related processes• Opportunity assessment

Finding: Process MisalignmentFinding: Process Misalignment

Product Development

Agile Process

Content Development

Traditional

Release 3.0

Finding: Process MisalignmentFinding: Process Misalignment

Product Development

Agile Process

Content Development

Aligned

Feature as ‘Content Envelope’Feature as ‘Content Envelope’

User Guide

Field Manual

Marketing

Content Analysis FindingsContent Analysis Findings

• Content audit• Redundancy and

overlap

• Gaps• Content to retire

Summary of FindingsSummary of Findings

Specialization ElementsSpecialization Elements

Specialization ElementsSpecialization ElementsA

ttributes

Structural Elements – MapsStructural Elements – Maps

Name Based On Contains Blocks

Owned by

UserGuide Bookmap IntroductionChaptersSupport GuideIndex

Tech Docs

ReferenceManual Bookmap DescriptionHowTosError Codes

Tech Docs

Feature DITA Map DescriptionHowTosError CodesConfiguration Notes

MarketingTech DocsQA

Block Elements – Topics and ConceptsBlock Elements – Topics and Concepts

Name Based On

Contains Notes

Description DITA Topic

KeywordsShortDescriptionMediumDescriptionLongDescription

ShortDescription Topic –Section

Paragraph Used in marketing materials, User Guide, Field Manual

MediumDescription Topic – Section

Paragraphs Used in marketing materials

LongDescription Topic – Section

SectionsParagraphs

Used in UserGuide

Inline Elements – DomainsInline Elements – Domains

Name Based On Notes

UI DITA UI domain Available: Paragraphs Table Cells

BrandElement Company specific domain

Available: Anywhere

Product names, etc.

Programming DITA programming Available: Anywhere

Only using 6 of the standard 25 elements, added 3 custom elements

Attribute SpecializationsAttribute Specializations

Name Based On Notes

@audience @audience Limit to following options: User Technician Internal-Only QA-Team

@translate @translate Limit to valid language codes (‘en,’ ‘fr,’ ‘de,’ etc.)

@legal_status @otherprops Required for specific block elements (e.g. copyright notice). Values(‘modified,’ ‘approved’)

Steps for Prototyping SpecializationSteps for Prototyping Specialization

1 Mock up representative content using generic DITA

2 Carefully review the existing domains and specializations

3 Remove as much as you can

4 Build the DTD

5 Revise mock up content with specializations

6 Iterate with SMEs

Specialization Best PracticesSpecialization Best Practices

Know the public DITA specializations

Know the current DITA domains

Preserve DITA Open Toolkit architecture

Specialization Best PracticesSpecialization Best Practices

Make sure DTD is easy to update

Support ‘default’ and ‘flexible’ formats containers

Create a DTD maintenance process

Questions and Next StepsQuestions and Next Steps

[email protected]

[email protected]

www.justsystems.com

[email protected]

1-866-793-1542