Agile Documentation Development Tim Grantham Team Leader, Documentation Standards October 30, 2008

Agenda About You About Me About Thermo Fisher Scientific and Thermo LAI About Agile Software Development About Agile Content Development About DITA and Agile Content Development Case Study: DITA @ Thermo LAI Q&A

About You

About Me

About Thermo Fisher Scientific and Thermo LAI

About Agile Software Development

About Agile Content Development

About DITA and Agile Content Development

Case Study: DITA @ Thermo LAI

Q&A

What is Thermo Fisher Scientific? “Thermo Fisher Scientific (NYSE: TMO) is the world leader in serving science, enabling our customers to make the world healthier, cleaner and safer.” Annual sales of more than $10 billion 30,000 employees 350,000 customers world wide

“Thermo Fisher Scientific (NYSE: TMO) is the world leader in serving science, enabling our customers to make the world healthier, cleaner and safer.”

Annual sales of more than $10 billion

30,000 employees

350,000 customers world wide

What is Thermo LAI? LAI: Laboratory Automation and Integration Founded as CRS Robotics in Burlington, Ontario, Canada about 25 years ago by robotics engineers from McMaster University. Acquired by Thermo in 2003 Brings the technologies, tools, and processes of automated manufacturing to the laboratory: Robots Workcell integration and control software Automation support hardware Automation design and system integration services

LAI: Laboratory Automation and Integration

Founded as CRS Robotics in Burlington, Ontario, Canada about 25 years ago by robotics engineers from McMaster University.

Acquired by Thermo in 2003

Brings the technologies, tools, and processes of automated manufacturing to the laboratory:

Robots

Workcell integration and control software

Automation support hardware

Automation design and system integration services

Smallest automated lab system: RapidStak TM bench top instrument loader Instruments from Thermo Controlled by Thermo LAI POLARA software running on a Windows ® PC Thermo LAI Products: Small Lab System

Smallest automated lab system:

RapidStak TM bench top instrument loader

Instruments from Thermo

Controlled by Thermo LAI POLARA software running on a Windows ® PC

Thermo LAI Products: Medium Lab System Small automated lab system for toxicological testing: Thermo LAI CataLyst Express bench top articulated robot Thermo Scientific reader and incubator Third party liquid handler Controlled by Thermo LAI POLARA software running on a Windows PC

Small automated lab system for toxicological testing:

Thermo LAI CataLyst Express bench top articulated robot

Thermo Scientific reader and incubator

Third party liquid handler

Controlled by Thermo LAI POLARA software running on a Windows PC

Thermo LAI Products: Large Lab System Big automated lab system for high throughput screening: Thermo LAI Distributed Motion robots Instruments and peripherals from Thermo and third parties Controlled by Thermo LAI POLARA software running on a Windows® PC

Big automated lab system for high throughput screening:

Thermo LAI Distributed Motion robots

Instruments and peripherals from Thermo and third parties

Controlled by Thermo LAI POLARA software running on a Windows® PC

POLARA lab automation software for Windows provides graphical user interface for: Configuring lab system Designing assays Scheduling samples Running experiments Collecting, processing, and exporting instrument data Thermo LAI Products: POLARA Lab Automation Software

POLARA lab automation software for Windows provides graphical user interface for:

Configuring lab system

Designing assays

Scheduling samples

Running experiments

Collecting, processing, and exporting instrument data

Who are Thermo LAI Customers? Big pharma: Pfizer, GlaxoSmithKline, BristolMyersSquibb, Novartis, etc. OEM partners: Molecular Devices, Nikon, etc. Research organizations: Whitehead Institute, TIGR, Mount Sinai, etc. Many smaller labs buy and use our bench top automation products.

Big pharma: Pfizer, GlaxoSmithKline, BristolMyersSquibb, Novartis, etc.

OEM partners: Molecular Devices, Nikon, etc.

Research organizations: Whitehead Institute, TIGR, Mount Sinai, etc.

Many smaller labs buy and use our bench top automation products.

Staff: three Deliverables: about 100 new and updated documents/year: Hardware and software user, unpacking, and setup guides Programming guides and references Service manuals Manufacturing work instructions Outputs: print, PDF, HTML Help, HTML Help 2, Web Help, SharePoint Help Legacy toolset: Adobe FrameMaker, Quadralay WebWorks Publisher 2003, Microsoft Visual Studio, and some custom XSL transforms Methodology: using single-sourcing to produce user documentation for multiple versions of LAI products, each published to multiple outputs Thermo LAI Technical Publications

Staff: three

Deliverables: about 100 new and updated documents/year:

Hardware and software user, unpacking, and setup guides

Programming guides and references

Service manuals

Manufacturing work instructions

Outputs: print, PDF, HTML Help, HTML Help 2, Web Help, SharePoint Help

Legacy toolset: Adobe FrameMaker, Quadralay WebWorks Publisher 2003, Microsoft Visual Studio, and some custom XSL transforms

Methodology: using single-sourcing to produce user documentation for multiple versions of LAI products, each published to multiple outputs

What is Agile Software Development? “Agile software development processes are in use at 14% of North American and European enterprises, and another 19% of enterprises are either interested in adopting Agile or already planning to do so.” “Early adopters of Agile processes were primarily small high-tech product companies. But a second wave of adoption is now underway, with enterprise IT shops taking the lead. These shops are turning to Agile processes to cut time-to-market, improve quality, and strengthen their relationships with business stakeholders.” — Forrester Research, November, 2005

“Agile software development processes are in use at 14% of North American and European enterprises, and another 19% of enterprises are either interested in adopting Agile or already planning to do so.”

“Early adopters of Agile processes were primarily small high-tech product companies. But a second wave of adoption is now underway, with enterprise IT shops taking the lead. These shops are turning to Agile processes to cut time-to-market, improve quality, and strengthen their relationships with business stakeholders.”

— Forrester Research, November, 2005

What is Agile Software Development? An iterative software development methodology based on a periodic publishing model Closely parallels Toyota’s Lean Product Development System, which is based on Toyota’s Lean Manufacturing System Evolved from the Rapid Application Development methodology that began to become popular in the 1980s Optimizes development adaptability, rather than predictability Requires disciplined and skillful practitioners Requires multi-disciplinary teams that includes user interface designers and technical writers

An iterative software development methodology based on a periodic publishing model

Closely parallels Toyota’s Lean Product Development System, which is based on Toyota’s Lean Manufacturing System

Evolved from the Rapid Application Development methodology that began to become popular in the 1980s

Optimizes development adaptability, rather than predictability

Requires disciplined and skillful practitioners

Requires multi-disciplinary teams that includes user interface designers and technical writers

Conventional Waterfall Product Development Process Software Product Development Presentation Layer (user interface, online help) Business Logic Layer (implements main functionality) Database Layer (manages persistent data) Customer Validation Requirements Approved Alpha Release Beta Release General Availability

Problems with Conventional Waterfall Development Tremendous waste Late Over budget Change intolerant Defective Conventional Waterfall Practices Yield 65% Wasted Features

Tremendous waste

Late

Over budget

Change intolerant

Defective

Agile Software Development Process 1a. Iteration requirements approved. 1b. Tests designed. 1c. Components coded, tested, documented, and completely debugged. 1d. Customer validated! Software Product 2a. Iteration requirements approved. 2b. Tests designed. 2c. Components coded, tested, documented, and completely debugged. 2d. Customer validated! Release Plan Presentation Layer (user interface, online help) Business Logic Layer (implements main functionality) Database Layer (manages persistent data) Iteration 1 Iteration 2 Iteration 3 Iteration 4 Iteration 5 Iteration 6 Iteration 7 Iteration 8 Iteration 9 Iteration 10

Benefits of Agile Software Development Provides continuous customer feedback during development Reduces risk Reduces waste Provide continuous feedback to management on development performance Improves timeliness Improves relevance

Provides continuous customer feedback during development

Reduces risk

Reduces waste

Provide continuous feedback to management on development performance

Improves timeliness

Improves relevance

Challenges of Agile Software Development It’s different.

It’s different.

Conventional Documentation Development Process Technical Publication Development Presentation Layer (page layout, text styles) Information Layer (text, graphics) Structural Layer (table of contents) Customer Validation Table of Contents Approved First draft Second draft General Availability

Problems with Conventional Document Development Tremendous waste Late Over budget Change intolerant Defective

Tremendous waste

Late

Over budget

Change intolerant

Defective

Benefits of Agile Documentation Development Permits continuous reader feedback during development Reduces risk Reduces waste Provides continuous feedback to management on development performance Improves timeliness Improves relevance

Permits continuous reader feedback during development

Reduces risk

Reduces waste

Provides continuous feedback to management on development performance

Improves timeliness

Improves relevance

Opportunities in Agile Documentation Development Enables technical communicators to add new and significant value: Provide guidance on or even lead the development of the user interface Become the development team’s manager of product terminology Take over content of user interface components (e.g. edit .resx files in .NET applications) “ The goal of testers is not to find bugs, but to prevent them.” — Mary and Tom Poppendieck, Implementing Lean Software Development: From Concept to Cash , “ The goal of technical communicators is not to explain confusing product features, but to prevent them.” — Tim Grantham, 2008

Enables technical communicators to add new and significant value:

Provide guidance on or even lead the development of the user interface

Become the development team’s manager of product terminology

Take over content of user interface components (e.g. edit .resx files in .NET applications)

“ The goal of testers is not to find bugs, but to prevent them.” — Mary and Tom Poppendieck, Implementing Lean Software Development: From Concept to Cash ,

“ The goal of technical communicators is not to explain confusing product features, but to prevent them.” — Tim Grantham, 2008

Challenges in Agile Documentation Development It’s different: Much more collaboration with other disciplines Daily updates on progress More frequent testing of quality A modular documentation methodology Separation of design, authoring, and publishing functions

It’s different:

Much more collaboration with other disciplines

Daily updates on progress

More frequent testing of quality

A modular documentation methodology

Separation of design, authoring, and publishing functions

Challenges in Agile Documentation Development Conventional desktop publishing tools are inadequate: Don’t easily support iterative document development Not easily integrated into software development environments Don’t permit a high degree of publishing automation Don’t easily support localization Don’t provide easy portability of content

Conventional desktop publishing tools are inadequate:

Don’t easily support iterative document development

Not easily integrated into software development environments

Don’t permit a high degree of publishing automation

Don’t easily support localization

Don’t provide easy portability of content

What is Agile Documentation Development? Based on the principles and practices of Agile Software Development Implements an iterative development process of modular documentation Uses software development-friendly, modular documentation-friendly, automation-friendly, localizable, portable DITA XML!

Based on the principles and practices of Agile Software Development

Implements an iterative development process of modular documentation

Uses software development-friendly, modular documentation-friendly, automation-friendly, localizable, portable DITA XML!

Agile Documentation Development Process Technical Publication 1a. Iteration DITA map approved. 1b. Topics authored, edited, and approved for publication. 1c. Customer validated! 2a. Iteration DITA map approved. 2b. Topics written, edited, and approved for publication. 2c. Customer validated! Release Plan Presentation Layer (page layout, text styles) Information Layer (text, graphics) Structural Layer (table of contents) Iteration 1 Iteration 2 Iteration 3 Iteration 4 Iteration 5 Iteration 6 Iteration 7 Iteration 8 Iteration 9 Iteration 10

How does DITA facilitate Agile Documentation Development? DITA content modeling corresponds well to user, task, and object modeling, enabling close collaboration with product managers and designers. DITA topics map easily to user interface components. DITA is modular. DITA uses text files, enabling tight integration with development.

DITA content modeling corresponds well to user, task, and object modeling, enabling close collaboration with product managers and designers.

DITA topics map easily to user interface components.

DITA is modular.

DITA uses text files, enabling tight integration with development.

How does DITA facilitate Agile Documentation Development? DITA facilitates automated measurement of quality across an arbitrary set of documents. DITA is designed to facilitate localization. DITA, because it is an OASIS standard, facilitates portability among teams and organizations, and frees technical communicators from bondage to proprietary tools.

DITA facilitates automated measurement of quality across an arbitrary set of documents.

DITA is designed to facilitate localization.

DITA, because it is an OASIS standard, facilitates portability among teams and organizations, and frees technical communicators from bondage to proprietary tools.

Case Study: Agile Documentation Development at Thermo LAI Cell Growth and Discovery WorkCell

Cell Growth and Discovery WorkCell

Case Study: Agile Documentation Development at Thermo LAI Celleste Software

Celleste Software

Case Study: Demonstration Designing the release plan

Designing the release plan

Case Study: Demonstration Designing the release plan (detail)

Designing the release plan (detail)

Case Study: Demonstration Designing the DITA topic map:

Designing the DITA topic map:

Case Study: Demonstration Designing the DITA topic map (detail):

Designing the DITA topic map (detail):

Case Study: Demonstration Authoring the DITA topic:

Authoring the DITA topic:

Case Study: Demonstration Publishing the DITA topics: PDF Output HTML Help Output

Publishing the DITA topics:

Demonstration: DITA Map2MIF Transform Custom transform generates unstructured FrameMaker book and chapter files from DITA map and topics

Custom transform generates unstructured FrameMaker book and chapter files from DITA map and topics

Demo: DITAMap2XLS Transform Custom transform generates Excel spreadsheet of quality metrics from DITA map and topics

Custom transform generates Excel spreadsheet of quality metrics from DITA map and topics

What does Agile Documentation Development mean for technical publication managers? To take advantage of the new opportunities to add value, technical publication managers must: Become collaborators in the entire product development process, from design to delivery. Learn and implement tools that integrate content design, development, and deployment into product design, development, and deployment. Redefine technical communication team roles: most experienced must devote their time to planning and design, least experienced to topic authoring. Develop familiarity with the standards, technologies, and methodologies of agile product development. Identify content quality metrics

To take advantage of the new opportunities to add value, technical publication managers must:

Become collaborators in the entire product development process, from design to delivery.

Learn and implement tools that integrate content design, development, and deployment into product design, development, and deployment.

Redefine technical communication team roles: most experienced must devote their time to planning and design, least experienced to topic authoring.

Develop familiarity with the standards, technologies, and methodologies of agile product development.

Identify content quality metrics

What does Agile Documentation Development mean to technical writers? To become valued members of agile development teams, technical writers must learn how to: Work on a multi-disciplinary team Create content modules (topics): not just writing information, but modeling it semantically Integrate their output into the product development infrastructure Engage in lots of interactive face-to-face communication (scrums)

To become valued members of agile development teams, technical writers must learn how to:

Work on a multi-disciplinary team

Create content modules (topics): not just writing information, but modeling it semantically

Integrate their output into the product development infrastructure

Engage in lots of interactive face-to-face communication (scrums)

What does Agile Documentation Development mean to the profession of technical communications? To become valued members of the business world, technical communicators must learn how to: Work with the development community to integrate content development methodologies with product development methodologies Demonstrate, with data, the value they bring to product development DITA, and its XML descendants and peers, will help transform technical communications from a craft to a science.

To become valued members of the business world, technical communicators must learn how to:

Work with the development community to integrate content development methodologies with product development methodologies

Demonstrate, with data, the value they bring to product development

DITA, and its XML descendants and peers, will help transform technical communications from a craft to a science.

Q&A Thank you for your attention!

Thank you for your attention!