collaborating to transition to topic-based authoring
TRANSCRIPT
1EMC ©2014
Collaboration
Richard L. Morris, Ph.D.Anita Gossett, M.S.
Transitioning to topic-based authoring
2EMC ©2014
Our Situation
How to transition a group of writers from theory and training into production using a DITA/CMS environment? Profile:
– 2 managers in Bangalore– 8 writers in the US in multiple locations– 12 writers co-located in Bangalore– 1 IA in the US– 1 IA in Bangalore
Mixed skill levels in DITA/CMS
3EMC ©2014
Our Problem (cont.)
Releases– 2 major releases 6 weeks away– 2 major releases in subsequent quarters– All products share same underlying technology
Content– Products share 30 - 40% of their base content– Previously each writer owned and authored a
single deliverable in FrameMaker– Now, everyone has to reuse – not author – the
base topics from the CMS
4EMC ©2014
How do we get everyone on the
same page?
5EMC ©2014
Solution
Hold a hands-on workshop to expose the issues Let the stakeholders propose solutions to the challenges of topic-based authoring Leverage their experience
– Collaboration was not new to them– the CMS was!
6EMC ©2014
Collaborative AuthoringAuthoring in a CMS is different
Different roles – Who does what?
Ownership– What do you mean I’m not doing the install guide?
Coordination– Who determines which topics go where?
Publishing– I write something but someone else publishes it?
Architecture– Following a reference model
7EMC ©2014
Workshop Schedule
Day 1: Intro and ATL planning– Collaborating in this new environment– SME explains the technology – Team breakouts
Day 2: Execution– Return to groups and build the content planned
out on the previous day according to the ATL
Day 3: Recap– Standards Review– Articulate what we learned – Fill out playbook templates
8EMC ©2014
Assigned very specific, goal-based tasks
Create content that explains how to create a report in EMC’s Watch4net productDeliverable
– WebHelp output
SME writer demonstrates how to create a reportTeams create the documentation
9EMC ©2014
Planning
10EMC ©2014
Planning a Frame book vs. a DITA pub
11EMC ©2014
Planning and ATLs
Planning in a CMS environment was the newest thing for the writersWhat is an ATL?
– Annotated Topic List
Purpose– Plan maps – Organize count– Manage workflow
12EMC ©2014
Sample ATL8 entries
13EMC ©2014
Production ATL72 entries to start
14EMC ©2014
What we did
Assigned an SME to explain the technology– He explained how to create a report
Provided resources– VM running the application and credentials– Repository folder for building your pub– Repository folder with existing content– Workshop kit with
▪ ATL templates▪ Current PDF of existing content
Instructions to get to the report screen
15EMC ©2014
Teams and roles
3 teamsEach team defines who needs to do whatEach team needs to create and deliver an ATL and final content for its taskDoc lead will be responsible for the coordinated ATL
16EMC ©2014
Outcome of the workshop
Self-defined rolesRules the writers developed for different scenariosExamples
– Single writer adding content to another writer’s pub
– Multiple writers contributing content to another writer’s pub
17EMC ©2014
Writers defined how they interactedLike colors represent overlap areas and affinities
ATL Manager
Map Manager
Content Developer
Publication Owner Editor Publication
Lead
Reuse Coordinator IA Doc Lead
18EMC ©2014
RolesContent structure
– ATL manager– Map manager– Reuse coordinator
Content itself– Content developer (writer)– Publication owner
People/project management– Doc lead– Pub lead
IA
19EMC ©2014
Scenarios• Single writer adding content to
another writer’s pub• Multiple writers contributing
content to another writer’s pub
20EMC ©2014
Adding content to a pub Single writer scenario
•This content was not part of the overall ATL planning for the publication.
• It came up in a scrum after the ATL was planned.
•The owner is unaware of this new content or that you have been working on it.
• The owner does not have a vested interest in developing the content.
Context
21EMC ©2014
Adding content to a pubSingle writer scenario (cont.)
• The writer contacts the publication owner via e-mail with the details.
• The owner and writer negotiate a space.• The publication owner includes the new
content in the ATL.• The writer adds it to the publication and
generates the publication.• The owner performs a final check on all
content in the publication during the final builds in the development process.
Rules
22EMC ©2014
Adding content to a pubSingle writer scenario (cont.)
•Content Developer•Doc Lead•Reuse Coordinator•ATL Manager•Publication Owner
Roles
*Role ≠ Resource
23EMC ©2014
Adding content to a pubMultiple writer scenario
•You are working on a project for which you have defined a large subsection that you plan to include in different publications.
• You may be the primary owner of one publication but not the other.
• You need to negotiate space and coordinate resources and content.
•One output is OLH, which goes into software build.
Context
24EMC ©2014
Adding content to a pub Multiple writer scenario (cont.)
•The doc lead for the subsection creates an ATL and sends it to the publication owners.
•The lead and owners negotiate a space.•The section planner adds the bridge topic for the section to the publication.
•The owners add the ATL for the subsection to the ATL for the publication.
•The writers add the content to the publication as the topics become ready.
•Anyone may generate the publication at any time to check the topics.
•The release owner generates a Help output for the software build.•The owner performs a final check on all content in the publication during the final builds in the development process.
Rules
25EMC ©2014
Adding content to a pubMultiple writer scenario (cont.)
• Content Developer• Doc Lead• Reuse Coordinator• ATL Manager• Publication Owners• Planner for the subsection who is
responsible for managing and coordinating it
• IA
Roles
*Role ≠ Resource
26EMC ©2014
Benefits of holding a workshop
Brings issues to light for management and writersStakeholders see each other’s issues from a peer-to-peer perspective Participants come away with skills and language to collaborate and focus efforts
27EMC ©2014
Production Scenario• 2 writers• 2 installation guides • 2 products• Shared content
28EMC ©2014
Reality check: Schedule and Resources
– Six weeks until release date– Two writers, one Information Architect (IA)– Two installation guides– 40% reuse– Writer 1: Two years experience with DITA/CMS,
familiar with product content and technology– Writer 2: Experienced writer, minimal experience
with current DITA/CMS. Unfamiliar with content.– IA: Two years experience with DITA/CMS. Focus
spread across multiple writing teams and projects.
29EMC ©2014
Reality check: RolesWriter 1 (many roles)
– Documentation Lead– ATL Manager– Publication Owner– Reuse Coordinator– Content Developer (Writer)
Writer 2 – Content Developer– ATL Manager– Publication Owner
30EMC ©2014
Reality check: Roles
Information Architect (IA) – Teaches collaboration workshop– Reviews ATLs early in planning process– Reviews topics and maps for adherence to
Documentation Reference Models and DITA standards
– Answers questions about tools and standards
31EMC ©2014
Examples
32EMC ©2014
Annotated Topic List (ATL)
33EMC ©2014
Map reuse guidelines
You can only reuse a map if – any change to the map would propagate to every
instance of its reuse
Build a new map and reuse topics in the original map if
– you are working in a different publication and you want to change some topics in the map
Mirror the name of the original map as much as possible so that you can maintain semantic connections across all uses of map
34EMC ©2014
Reusing a map directly
35EMC ©2014
Using a map as a basis for another map Map – Product 2
1. srm_map_1a. w4n_task_1b. srm_task_2c. w4n_task_3
Map – Product 1
1. w4n_map_1a. w4n_task_1b. w4n_task_2c. w4n_task_3
36EMC ©2014
MetricsMeasure your progress
– Number of topics in publication– Number of maps in publications– How much content is reused across other
publications? ▪ Example for Product 1 Install Guide (175 topics in final
version):— 64% of the topics were unique to Product 1— 34% of the topics were reused from Product 2 (core)— 2% of the topics were reused from Product 3
37EMC ©2014
Summary: Practical tips and tricksDecide which roles apply to your project
– Collaboration is critical with multiple roles/people
Capture and socialize changes in process– Topics can be reused more easily than maps– Writers own topics, not books
Insist on Management support– Don’t expect speed! Allow at least six months– Gather metrics to show progress
Celebrate your progress– Reward employees as they make the transition
38EMC ©2014
Questions?