Collaborating to Transition to Topic-Based Authoring

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

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

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

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

Collaborating to Transition to Topic-Based Authoring

Technology

Transcript of Collaborating to Transition to Topic-Based Authoring