The world leader in serving science

Agile Documentation Development

Tim GranthamTeam Leader, Documentation Standards

October 30, 2008

2

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

3

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

4

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

5

Smallest automated lab system:• RapidStakTM bench top instrument loader• Instruments from Thermo• Controlled by Thermo LAI POLARA software running

on a Windows® PC

Thermo LAI Products: Small Lab System

6

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 runningon a Windows PC

7

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 runningon a Windows® PC

8

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

9

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.

10

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

11

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

12

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

13

Conventional Waterfall Product Development Process

Presentation Layer(user interface, online help)

Business Logic Layer(implements main functionality)

Database Layer(manages persistent data)

Software Product

Development

CustomerValidation

RequirementsApproved

AlphaRelease

BetaRelease

GeneralAvailability

14

Problems with Conventional Waterfall Development

Tremendous waste Late Over budget Change intolerant Defective

Conventional Waterfall Practices Yield 65% Wasted Features

15

1a. Iteration requirements approved.

1b. Tests designed.

1c. Components coded, tested, documented, and completely debugged.

1d. Customer validated!

Agile Software Development Process

Presentation Layer(user interface, online help)

Business Logic Layer(implements main functionality)

Database Layer(manages persistent data)

Software Product

Iteration 1Iteration 2

Iteration 3Iteration 4

Iteration 5Iteration 6

Iteration 7Iteration 8

Iteration 9Iteration 10

2a. Iteration requirements approved.

2b. Tests designed.

2c. Components coded, tested, documented, and completely debugged.

2d. Customer validated!

Release Plan

16

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

17

Challenges of Agile Software Development

It’s different.

18

Conventional Documentation Development Process

Presentation Layer(page layout, text styles)

Information Layer(text, graphics)

Structural Layer(table of contents)

Technical Publication

Development

CustomerValidation

Table of ContentsApproved

First draft Second draft GeneralAvailability

19

Problems with Conventional Document Development

Tremendous waste Late Over budget Change intolerant Defective

20

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

21

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

22

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

23

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

24

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!

25

Presentation Layer(page layout, text styles)

Information Layer(text, graphics)

Structural Layer(table of contents)

Technical Publication

1a. Iteration DITA map approved.

1b. Topics authored, edited, and approved for publication.

1c. Customer validated!

Agile Documentation Development Process

Iteration 1Iteration 2

Iteration 3Iteration 4

Iteration 5Iteration 6

Iteration 7Iteration 8

Iteration 9Iteration 10

2a. Iteration DITA map approved.

2b. Topics written, edited, and approved for publication.

2c. Customer validated!

Release Plan

26

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.

27

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.

28

Case Study: Agile Documentation Development at Thermo LAI

Cell Growth and Discovery WorkCell

29

Case Study: Agile Documentation Development at Thermo LAI

Celleste Software

32

Case Study: Demonstration

Designing the DITA topic map:

33

Case Study: Demonstration

Designing the DITA topic map (detail):

34

Case Study: Demonstration

Authoring the DITA topic:

35

Case Study: Demonstration

Publishing the DITA topics:

PDF Output

HTML Help Output

36

Demonstration: DITA Map2MIF Transform

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

37

Demo: DITAMap2XLS Transform

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

38

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

39

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)

40

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.

41

Q&A

Thank you for your attention!