Collaborative Authoring in DITA, or: How We All Learned to Share
James HomEngineering Program Manager
© 2010 NetApp. All rights reserved. 3
Global Leadership
Broad solutions portfolio Comprehensive professional
services Global support Industry-leading partners 135+ offices around the world ~8000 employees Fortune 1000, S&P 500,
NASDAQ 100$1B
$3B
$4B
$2B
0706050403 08
FY09:$3.5 Billion*
09* Non-GAAP Revenue
3
© 2010 NetApp. All rights reserved. 44
Extend Efficiencies Everywhere
NetApp® FAS and V-Series
High-End SAN
Low/Midrange SAN
NAS
Disaster Recovery
Archive & Compliance
Backup
Virtualization
Industry Approach
All runData ONTAP®
Different hardwareDifferent softwareDifferent people
Different processes
Same hardwareSame softwareSame people
Same processes
▪One platform for all workloads▪ Learn once, deploy everywhere▪ Improve IT and business efficiency
4
© 2010 NetApp. All rights reserved. 5
Before DITA: Single writer owns one book
1990s technology:– Unstructured
Framemaker & Robohelp
1790s ownership:– One writer, one book– One work of content,
lovingly hand-crafted from start to finish
– Content used only in that book
– Writing groups focused on output formats
Image source: Wikipedia Commons
© 2010 NetApp. All rights reserved. 6
With DITA: Share and reuse the work
Now: Interchangeable parts:
“topics”– Multiple authors per deliverable– Content written for any output
format– Content reusable in multiple
deliverables
© 2010 NetApp. All rights reserved. 7
Writers own relationships and technologies, not books
Sunnyvale
RTP
Bangalore
Waltham
7
Pittsburgh
© 2010 NetApp. All rights reserved. 8
Component CM lets us share work globally: topics written once are used everywhere
Sunnyvale
RTP
Bangalore
8
WalthamPittsburgh
© 2010 NetApp. All rights reserved. 9
Writers manage groups of topics with submaps
Sunnyvale
RTP
Bangalore
9
WalthamPittsburgh
© 2010 NetApp. All rights reserved. 10
Publication captain builds deliverable using a master map
10
Publication Captain
Publication
Deliverable outputsMaster map
© 2010 NetApp. All rights reserved. 11
Collaboration requires additional communication between topic owners
11
© 2010 NetApp. All rights reserved. 12
Cross-global, cross-timezone communication via workflow states
12
© 2010 NetApp. All rights reserved. 13
DITA’s structure isn’t enough to ensure reusability
13
Writing style and usage DITA style and usage Editors ensure common voice Tools (Author Assistant) as
“Power Style Guide”
Style rules
Conrefs and Variables controlled in libraries
Conditions centrally managed and owned by the “Condition Maven”
Future: controlled vocabulary for translation
Shared constructs
© 2010 NetApp. All rights reserved. 14
Team representatives define process and content rules for the organization
Decisions affect the entire organization, so include representatives from each writing group, editors, and tools.
Ensures buy-in and coverage of all issues.
Need agreement otherwise can’t share everywhere.
© 2010 NetApp. All rights reserved. 15
The most important thing: Trust
Collaboration at this scale requires a high level of trust in your colleagues.
– Trust that their writing is good enough for your deliverable.
– Trust that they got the technical details right.
– Trust that they got the content edited and reviewed and fixed any errors.
Confidential. The material in this presentation is the property of Fair Isaac Corporation, is provided for the recipient only, and shall not be used, reproduced, or disclosed without Fair Isaac Corporation's express consent.© 2009 Fair Isaac Corporation. 16
Packages, Use Cases, and TopicsDefinitions and Artifacts to Facilitate Documentation Reuse
Tom GoeringFair Isaac Corporation
© 2009 Fair Isaac Corporation. Confidential.17
The Challenge
We need to manage:
» User tasks associated with product functionality
» Common tasks/functions shared across multiple products
» Product-specific tasks/functions
» DITA topics that support each task
» Reuse of topics that support common tasks
» Integration of common topics and product-specific topics in deliverables
© 2009 Fair Isaac Corporation. Confidential.18
Definitions
» PackageA container, representing an area of product functionality, that contains
use cases, and optionally actors, subsystems, and subpackages.
» Use CaseFor our purposes, we consider “use case” a synonym for the more
commonly understood “user task.” The official UML definition is: “A description of a set of sequences of actions, including variants, that a system performs that yields an observable result of value to an actor.” I don’t believe there is any inherent conflict with our usage.A use case is contained by exactly one package. However, a use case can “include” other use cases, from the same package or a different package.
» TopicA DITA topic, owned by exactly one use case.
© 2009 Fair Isaac Corporation. Confidential.19
Artifacts
» UML ModelsA model includes at least one package, actor, and subsystem, and can represent either a common functional component such as Case Manager or ADAM, or a business application.
» Repository FoldersThe Trisoft folders correspond to the packages
» MapsEach use case has a corresponding map, with references to the topics for the use case
» TopicsA topic supports exactly one use case.
© 2009 Fair Isaac Corporation. Confidential.20
UML Use Case ModelTree view shows hierarchy; diagrams show relationships
» Packages are hierarchical. A package that contains one or more subpackages is a “parent.” A package that is contained by another package is a “child.”
© 2009 Fair Isaac Corporation. Confidential.21
Use Cases Can “Include” Use Cases From Other Packages
» Use cases can “include” other use cases. When a use case includes another use case, the topics associated with the included use case must integrate cohesively with those of the including use case.
© 2009 Fair Isaac Corporation. Confidential.22
Folders in the Repository Follow the Package Structure
» Each “package” folder contains a “Maps” folder, which includes the map for each use case in the package
© 2009 Fair Isaac Corporation. Confidential.23
Ownership
An Information Architect owns the model Responsible for the package and use case definitions, including the
parent/child and include relationships.
A Writer owns a package (more likely many packages….)Responsible for developing the topics and maps associated with each
use case in the package.
A Publication Lead owns a deliverableResponsible for assembling the deliverable from the content in the
packages.
© 2009 Fair Isaac Corporation. Confidential.24
Other Ownership Responsibilities
The Information Architect:» Interacts with PM, the GAT, and Dev Leads to validate the model. » Communicates with package owners about the scope and purpose of the
package.» Communicates with Publication Lead to identify and fill any gaps in the
“story” for a deliverable
The Writer:» Interacts with SMEs for the package to obtain source material and reviews.» Communicates with the owners of any parent, child, and included packages
to ensure cohesion between related topics.» Communicates with Publication Lead to ensure the suitability of the topics for
inclusion in the deliverable.
The Publication Lead:» Interacts with Product PM to define the deliverable and obtain reviews.» Communicates with IA and Writer to ensure comprehensive and cohesive
content.
26
Content In Business
Images
Specifications
Video
Websites
Documentation
Service Manuals Brochures
User Interfaces
150 countries and many more websites Up to 24 languages 10% content growth per year Time-to-market issues Unable to reach local audiences Personalized documentation spiraling out of
control (over 500 per product) High Desktop Publishing (DTP) costs for printed
materials Hard to find the relevant parts
27
Contracting Product Life Cycles
Research & Development
Market Life
PRDInternational
ReleaseEnglish Release Shelf Life
Trad
ition
al
Research & Development
Global Revenue & Market Capture Life
Mod
ular
writ
ing
LocalizationAuthor Review Publish
Author Review Publish Localize
Key:
28
Content Ownership and Communication
How do you manage content ownership?How communicated to a global team?How do you manage changes over time? Business requirements Products User community
30
Component Content ManagementManaging topic reuse ownership
• Reduces authoring effort
• Reduces mistakes
• Reduces review costs
• Reduces localization costs
• CCM defines ownership
• User roles
• Group membership
31
Component Content Management BenefitsMeet time to market challenges
See status of all objects to closely track to delivery date
32
Component Content Management BenefitsImprove customer satisfaction – always latest content
Automatic notification of newer versions
33
Component Content Management BenefitsClear ownership and audit trails
Track who makes changes to a Publication
35
Thank You for Joining Us
For more information…Visit us on the web: www.sdl.com/xml
Join us for our next DITA webinar…
How to Achieve Dynamic Publishing with DITATuesday, April 27, 2010To register:http://www.sdlxysoft.com/en/news-and-events/events
Top Related