Making it Real: Implementing DITA for Cisco IOS Technical Documentationdownloadcentre.sdl.com/tridion/pdf/boston/Cisco_Systems... · 2012-11-27 · Implementing DITA for Cisco IOS

© 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


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.


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


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.


What we deliver today

Configuration Guides


What we deliver today

Command references


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.


How do we take this…


…and this…


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


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


We use DITA, of course!


Episode III: Making it Real


Starting with the Business Requirements


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


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.


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.


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


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


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


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.







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.


Mapping Content Structures to DITA


Mapping Content Structures to DITA


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


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.


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.


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.


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.


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.


Defining workflow

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


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.


Getting There – Putting it Together

Develop design/functional specifications

Implement, integrate, and configure tools

Develop training plan

UAT and beta test systems

Rollout


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.


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!


Documents

Making it Real: Implementing DITA for Cisco IOS Technical Documentationdownloadcentre.sdl.com/tridion/pdf/boston/Cisco_Systems... · 2012-11-27 · Implementing DITA for Cisco IOS