Making it Real: Implementing DITA for Cisco IOS Technical...

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 1

Making it Real: Implementing DITA

for Cisco IOS Technical

Documentation

Mark Novembrino, Senior Technical Writer

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 2

Focus

Cisco has over 65,000 employees, and many tech doc groups with diverse requirements.

“Making it Real” is about the path to implement DITA for Cisco IOS Technical Documentation, not all of Cisco.

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 3

Cisco IOS Tech Docs – What We Do

Deliver technical documentation for:•10 Cisco IOS software trains•30+ Cisco IOS software releases•4000+ Features•16K+ Commands•45+ Technologies•Multiple platforms

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 4

Cisco IOS 101

Cisco IOS trains represent a collection of features intended to run on one or more hardware platforms and to meet a market requirement.

Cisco IOS “releases” represent the successive iterations of a train.

The feature set for a given train changes throughout the Cisco engineering development process, and features move in and out of a given release. Features are also “ported”, i.e., a feature in a given release is implemented in another release.

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 5

What we deliver today

Configuration Guides

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 6

What we deliver today

Command references

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 7

So What’s the Problem?

Customers are asking for more (dynamic retrieval of information, customized content, wiki-based delivery, etc.)

Customers need to access information based on their products, their software installs, and their feature sets.

The existing model does not scale.

Translation is difficult and poorly implemented.

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 8

How do we take this…

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 9

…and this…

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 10

IP Services and Ease of Deployment

• Security, Firewall, Intrusion Detection

• IP Telephony

• Wireless Networking

• QoS / Service Assurance

• IPv4 and IPv6 Routing

IP Services and Infrastructure

• High-End Platform Support

• Core and Edge IP/ MPLS Routing

• MPLS Virtual Private Networks (AToM)

• Enterprise Core Infrastructures

Scale and Availability

• Core IP/MPLS Routing

• Large-Scale Peering

• PoP Consolidation

• Converged Packet Infrastructures

• Continuous System Operation

Cisco IOS SoftwareM/T Releases

Cisco 7x00Cisco

3800Cisco800

Cisco 1800

Cisco 2800

Cisco 6500

Cisco 4500

Cisco 3750

Cisco 2970

Cisco ASR 1000

Cisco ASR 9000

Cisco 7600

Enterprise/SP Edge(Cisco Catalyst switches

Cisco 7x00 and 10000 Series)

Service Provider Core(Cisco 12000 and CRS-1 Series)Access

(Integrated Services Routers)

CRS-1

Cisco IOS Software 12.2S Releases

Cisco IOS XRSoftware

…and this…

Cisco ASR 5000

Cisco Nexus 7000

CRS-3Cisco 12000

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 11

And deliver this…

Integrated repository of common, reusable, managed content components

Coordinated workflow for content development, sharing, and translation

One-to-many output to a variety of formats (HTML, PDF, online help, eReader/Kindle, etc.)

Customized and dynamic content delivery

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 12

We use DITA, of course!

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 13

Episode III: Making it Real

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 14

Starting with the Business Requirements

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 15

Getting There - Defining Business Requirements

Examine existing processes

Examine existing deliverables

Coordinate with marketing and engineering processes

Consider market trends

Interview customers

Review web site feedback

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 16

Getting There – Analyzing Content

How does the existing content design synch with the business requirements? Where are the gaps?

Follow a top-down approach. Look at the larger chunks and work down into the smaller bits.

Identify patterns of commonality and reuse.

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 17

Getting There – Developing an Information Model

The content architecture looks at the big picture.

The information model look as the big picture, but also drills down into the details.

No “official” definition of these terms, however. The purpose of both designs is to map your content to the XML structures in a constructive way.

We started with in-house DTDs, and then decided to move to DITA.

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 18

What is DITA? DITA (Darwin Information Typing Architecture) is an XML-based

information architecture defined and maintained by the OASIS* technical committee. Originated at IBM and was donated by IBM.

Darwin: DITA utilizes principles of inheritance for specializationInformation Typing: Focuses on the meaning and purpose of the content (concept, task, reference)

Architecture: DITA offers a model for extension both of design and of processes

*OASIS = Organization for the Advancement of Structured Information Standards

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 19

Publication Flow

Map

Topic

Topic

Topic

Topic

Topic

Topic

BookMap

Map

Topic

Topic

Map

Topic

Topic

Topic

Topic

Topic

Topic

Topic

Topic

Topic

Topic

Topic

Topic

Topic

Topic

D

I

T

A

O

T

Topic Creation Assembly (Maps/BookMaps) Transformation Output

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 20

OASIS standard – Tangible DITA support from OASIS community – we are all facing the same challenges!

Information exchange – For example, partner and OEM documentation must be embedded in own documentation

Leveraging popular tools – Tool support for DITA is growing (SDL Trados, Just Systems, ArborText, AntennaHouse, ...)

Proven methodology – Topic-based writing has a proven success

Community development – new information types, improved processing, ...

No need to reinvent the base vocabulary - Create a DTD in 1/2 day with 10 lines vs. 6 months with 100s of lines; automatically pick up changes to the base

Avoid enormous vocabularies – Plug-in the DTDs for your requirements

Interoperability at the base type – Guaranteed reversion from special to base

Fast prototyping – People can be convinced quicker because base processing will also apply to specialized elements

Support for extending the architecture quickly and reusing investment in transformation logic

Why DITA – the Generic Answers

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 21

Why DITA – for Cisco IOS Docs

It perfectly models the component level structures (concept, reference, and task topics) that we’ve already created.

It is designed to deliver exactly the sort of dynamic content defined as part of our business needs.

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 22

Getting There – Developing an Information Model

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 23

Getting There – Developing an Information Model

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 24

Getting There – Developing an Information Model

The most critical activity is to engage end users (i.e., technical writers) in the development of the info model. They understand their content and the end goal of that content.

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 25

Mapping Content Structures to DITA

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 26

Mapping Content Structures to DITA

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 27

Getting There – Finding the Tools

There are many components to consider:•Conversion/Migration•Rendering•Authoring•Review•Publishing•Workflow•Content Management• Integration with Databases and Metadata

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 28

Getting There – Finding the ToolsPoints of Research:

•Existing tools in the company•Conferences•DITA and XML web resources• Industry experts and consultants

The most critical activity is to get end users early access to tools and listen to their feedback prior to purchase.

No technology religion.

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 29

Getting There – Finding the Tools

Our choices:•Conversion/Migration – Custom tools developed in house.•Rendering – DITA Open Toolkit / Stylesheets developed in house

•Authoring – Xmetal 5.5/6.0•Publishing – Custom tools developed in house.•Content Management – SDL Trisoft 2011• Integration with Databases and Metadata – Custom tools developed in house.

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 30

Why We Chose Trisoft Addressed all of our business requirements

Full support for all DITA functionality out-of-the-box.

XML-based repository with version control, security, taxonomy and search

Integration with leading XML authoring tools (XMetal, ArborText, and FrameMaker)

Conditional text and variables

Assembly of publications with version control on included content

Multilingual environment with translation management and in-context pre-translation

Integrated workflow

Highly intuitive, well-designed user interface

Engaged and committed support team

Our users *like it*…it models a process with which they are familiar.

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 31

Getting There – Defining Content Architecture

Why did does this slide appear *after* “finding the tools”?

Because knowing something about the tools may affect how you define your content architecture. Both activities are related. Of course, the content architecture must drive the tools (not the other way around), but understanding the tools may “inspire” changes to the architecture.

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 32

Defining Workflow

Top-down approach•Train lead runs tool to build feature list•Feature list is converted to a DITA topic map•A feature tracking publication drives workflow based on the feature list / topic map.

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 33

Defining workflow

•It’s important to be “realistic” with workflow.•Simple is good.

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 34

Getting There – Drafting the System Architecture

Defines all of the components and the interactions and communications between each.

Useful for developers to see the big picture and how their bit relates to the whole.

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 35

Getting There – Putting it Together

Develop design/functional specifications

Implement, integrate, and configure tools

Develop training plan

UAT and beta test systems

Rollout

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 36

Where we are today?

A fully-implemented system ready to roll out to production.

Early adopters developing and publishing content.

Training plan in place.

Full migration of content underway.

Roadmap for the future.

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 37

Lessons Learned There are many moving parts. Find the right tools for

the job.

Remember that the tools are not the solution. They are a means to an end.

Usability is the goal: The system has to get the job done…what was defined in the business requirements…but people also have to like it!

Follow an inclusive process.

Debunk the “afraid of change” myth: In the tech doc community, writers are not “afraid of change”. They just don’t have time for change. The system has to improve processes, not make them harder!

© 2006 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialPresentation_ID 38