@LavaCon

Case study:Serving authors’ needs

in a brave new DITA worldMike McGinnis

Julie Atkins

@LavaCon

About the Speakers

• Mike McGinnis

• Julie Atkins

MJ

On the road to DITA

1. Where we were

2. How we started

3. What we’re learning

4. Where we’re going

5. The biggies and freebies

@LavaCon

J

1 WHERE WE WEREOur story…

@LavaCon

J

The “Rig”

1.1 Staff, Content, Tools

• Writers– 2 full-time Tridium writers– 2 contract writers (added ~ 2010)

• Content– 80% DocBook– 5% DITA– 20% unstructured

• Tools & Workflows– Variety of non-standard tools– Variety of workflows

@LavaCon

M

Tools and Workflows (cont.)

@LavaCon

Content Type Tools Process

Software• NiagaraAX-3.x •FrameMaker 7.2, 8, 9, 10

•DocBook stylesheets (docbook-xsl-1.71.1 customized)•Saxon processor•Custom xsl processing as part of the s/w build•DITA OT (another rig?)

FM > XML > HTML

• Appliance Guides •FrameMaker•WebWorks•InsetPlus (FM plugin)•AXCM (FM plugin)

FM > HTML

• Other (Developer) •Word, Acrobat Pro•Dreamweaver (CSS &HTML editing)•Acrobat Pro

•Word > PDF•HTML >PDF

Hardware• Installation Guides •FM-7.2 FM > PDF

M

1.2 What we realized

• Problems ahead– More Writers– Mixed Toolsets– Mixed Processes

• Justification for change– Avoid disaster– Take advantage of new technologies (DITA)– Increase productivity– Scalable for future growth

@LavaCon

M

1.3 What we planned

• New Tech Pubs processes– Make DITA the Tridium standard– Move to task-based documentation– Learn to use minimalism principles– Content inventory and analysis

• New Tech Pubs tools– Standardized– Scalable– DITA compatible

@LavaCon

M

1.4 What we needed

• Education and training– Make DITA the Tridium standard– Move to task-based documentation– Learn to use minimalism principles

• Help from an expert(s)– Choosing tools– Installing and configuring CCMS– Performing content inventory and analysis

• Meet ongoing documentation deadlines@LavaCon

M

2 HOW WE STARTEDAfter years of dreaming…

@LavaCon

J

2.1 What we purchased

• Mentoring from Single Sourcing Solutions– Purchasing, spec’ing process– Installation– “Jump Start” process

• Arbortext Tools from PTC– Arbortext Editor– Arbortext Styler– Arbortext Publishing Engine– Arbortext Content Manager

• Arbortext eLearning Library

@LavaCon

M

2.2 Building on experience

• We already know “structured”– DITA “Topics” similar to DocBook <Sections>– DITA “Tasks” are like DocBook <Procedures>

• DITA is different but draw on familiar concepts– XML markup– Non XML markup (format catalogs/styles)

• FM users and styles• Word users and styles

@LavaCon

M

2.2 Experience (continued)

@LavaCon

DocBook “Procedure”

DITA “Task”

2.3 Content analysis

• Driver docs• Met weekly with mentors• Content analysis• Task analysis• Results

– Reuse potential– Standardized topic list

@LavaCon

J

2.4 Tech Doc Standards

• Style Sheet development– DITA tagging and highlighting guide– DITA style guide

• Code review• Process review

@LavaCon

M

3 WHAT WE’RE LEARNINGOn the road to DITA…

@LavaCon

J

File explosion

3.1 Adapting to DITA Environment

• File explosion uneasiness• One FrameMaker Chapter

is now “many” files

@LavaCon

M

File explosion

3.1 Adapting (continued)

• Tool helps and hindrances• Trusting CCMS not file naming conventions• Configure CCMS to help with your workflow• Possible tool confusion with new interface and tool

legacy terminology (not for writers)

• DITA helps and hindrances• DITA Maps can help• DITA Maps can hurt

• Learn how to use your new tools – discuss with the group regularly

@LavaCon

M

3.1 Adapting continued

• Getting good at searching your content– Understand DITA metadata features– Standardize, “use a taxonomy”

• Learn as you go, not in isolation– eLearning and working– Refer to your Style Guides– Refer to reference books– Refer to peers – discuss

@LavaCon

M

3.2 Content

• Have a strategy for legacy content• Know your subject• Standardize topic/book outline

– One task per topic; no subtasks– Install, configure, test

• Develop consistent naming conventions• Use throw-away DITAmaps

@LavaCon

J

3.3 Content challenges

• Remain task oriented when documenting features

• Some features don’t need doc!

@LavaCon

J

3.3 Standards

• Communicate and compromise– Writing style and element (tag) usage– Process– Content (reuse opportunities)

• Review markup and usage– Consistent markup enables reuse– Taking advantage of reuse opportunities

@LavaCon

M

3.4 Get help

• Use examples to learn to think DITA

• Use the experts– Consultants– Forums

• Documentation and Technical Writing Management

@LavaCon

M

3.4 Get help continued

• Read books and refer to them often!

@LavaCon

M

4 WHERE WE’RE GOINGBriefly…

@LavaCon

J

4.1 Align docs with agile

• Topics become part of Sprint planning• Reviews become smaller “sprint-friendly”• Engineers are more aware of content

development and review

@LavaCon

M

4.2 Implement doc life cycle

• Take advantage of the CCMS– Workflow– Status– Baselining– Revisioning and archiving

• Adapt agile tools (JIRA) to documentation process

@LavaCon

M

4.3 Alternate content delivery

• Make content available everywhere• Support product branding• Translation

@LavaCon

M

4.4 Comfort level

@LavaCon

J

• DocBook works in Arbortext Editor• We can get our work done while

implementing the new system• Our comfort level is growing

5 THE BIGGIES AND FREEBIES

We hope you take away…

@LavaCon

5.1 The biggies

• Power of analysis• Mindset shift

– Use examples– Talk to each other

• Get good help– Single Sourcing Solutions

• Stay the course

@LavaCon

J M

5.2 Freebies

• Content analysis spreadsheet• Task analysis interview outline• Links to our best books• A collection of other useful links

Email: Julie Atkins

@LavaCon

M