Developing DITA Expertise Across Your Virtual Team. Martha Morgan Architect, Information Engineering October 14, 2009

Transcription

1 Developing DITA Expertise Across Your Virtual Team Martha Morgan Architect, Information Engineering October 14, 2009

2 About NetApp Information Engineering Produces documentation for NetApp storage and datamanagement solutions User manuals Configuration guides Online Help Installation posters Over 70 members, including writers, editors, production staff, tools team, program managers, architect, and managers Global organization with teams in Sunnyvale, Pittsburgh, RTP, Boston, and Bangalore Most of NetApp s DITA leadership is in Sunnyvale, but more than half of the DITA users are somewhere else 2

3 NetApp s move to DITA Original motivation: XML would give us the flexibility to repurpose our content into different vehicles Content leverage get the most out of our content and thereby increase our value within the company NetApp began migrating content to DITA in 2006 Two DITA pilots Existing book content reused between two products New content (new product) developed by multiple writers and reused between deliverables As of October 2009, NetApp has over 13,000 topics in our CMS Tools in our authoring environment XMetaL Author, Enterprise Edition 5.1 (5.5 in the lab) SDL Trisoft InfoShare (3.8.4 in the pipeline) SDL Author Assistant (27 licenses, mostly for writers in India) Legacy tools: FrameMaker 7.2, RoboHelp X5, WebWorks 8 3

4 What DITA is providing to NetApp so far Content re-use between different types of deliverables Within the same product (online help, admin guides, best practices) Across multiple products NetApp- and IBM-branded documentation from single source Improved consistency in writing and organization Due to both structured writing and increased emphasis on consistency to support reuse Flexibility to respond to late changes 4

5 Challenge addressed in this presentation You ve put your virtual team through DITA training You ve built out your DITA tools infrastructure Authors in all locations are transforming DITA topics successfully But when you look closely, the DITA quality of the content just isn t that great What can you do? 5

6 Recommendations Make it easier for staff in remote offices to ask questions, provide feedback, and participate in infrastructure development Invest in DITA education Give priority to developing the DITA skills of leaders in each office Develop shared criteria for evaluating DITA skills 6

7 Make it easier to ask questions, provide feedback, and participate in infrastructure distribution list for DITA questions Or use the communication tool of your choice Let writers do most of the answering Teaches writers to seek out the expertise of their peers Intervene only if someone gives bad advice or if no one has responded after a long wait Create searchable archive In-house DITA wiki Links to standards, content models, meeting minutes, training modules, the DITA spec, etc. Indexed for better findability Don t let maintaining the wiki become a spectator sport Don t repeat answers point people to the wiki! 7

8 Make it easier to ask questions, provide feedback, and participate in infrastructure Real-time meetings of the DITA community Gets writers talking who are geographically or organizationally far apart Everyone gets the same information at the same time Helps avoid development of distinct DITA writing styles in different areas (bad for reuse) Requires some flexibility to accommodate all time zones Don t use a conference room; make everyone a remote caller 8

9 Make it easier to ask questions, provide feedback, and participate in infrastructure Architecture team of representatives from different groups, including Editorial and Tools Handles issues pertaining to the reader s experience of our content or to infrastructure issues impacting content Develops standards, best practices, and processes for DITA writers Complemented by another team of representatives that handles issues pertaining to tools Gives remote DITA writers a venue for bringing up issues Cross-department reality check for architecture decisions 9

10 Make it easier to ask questions, provide feedback, and participate in infrastructure Architecture team of representatives from different groups, including Editorial and Tools (continued) Provides status to DITA leadership on how teams are coping with the transition to DITA Grows DITA leaders throughout the department Be thrifty with meeting time Use other ways to communicate when practical Delegate the drafting of standards Overcome the legacy of silo writing: bring examples! Take meeting notes that get posted where the rest of the DITA community can access them easily 10

11 Invest in DITA Education Repeatable, stand-alone training modules At NetApp, our DITA training modules are simple presentations with voiceovers and accompanied by hands-on exercises nothing fancy Particularly good feedback from senior staff Available anytime to DITA writers at all locations Helps writers refresh their understanding of DITA concepts 11

12 Invest in DITA Education DITA topic reviews Based on code-inspection techniques used by software engineers Purpose is to have a team of your peers identify DITA defects, not solutions NOT a performance-evaluation tool for individual writers Emphasis on getting reviewers from other teams or offices Only a few topics can be reviewed in a single meeting Total cost of review team prep time can be daunting 12

13 Invest in DITA Education DITA Content Reviews One reviewer s look at about 50 pages of DITA-based output from one project See the DITA content as the customers will Reviewer employs a reusable tracking spreadsheet for identifying DITA defects: Description of defect How defect was detected (i.e., how can I tell there s a DITA defect from looking at the output?) Why the defect is a problem for customers or for other writers Reviewer updates spreadsheet to indicate locations of each defect in the reviewed content Meets with project team (writers and editor) to go over spreadsheet by defect type Emphasizes correctly structured DITA content 13

14 Invest in DITA Education Defect category and descriptions How to detect Impact Locations of instances of the defect in the review sample 14

15 Invest in DITA Education Don t let the demands of learning how to write in DITA distract your team from keeping up their customer knowledge The structure of DITA topics makes gaps in a writer s customer knowledge more conspicuous How to write the <shortdesc>? The <context>? Writers who don t understand who their customers are and what the customers goals are will get very frustrated You can t architect around a lack of customer knowledge If they don t understand their customers, writers can become at best good DITA taggers, but not good DITA writers 15

16 Develop DITA skills of leaders As you build the collaborative working environment that DITA requires, writers rely more and more on their peers for information Writers with questions tend to go to the leaders (official or social) of their group Given a choice between asking a grumpy expert or a novice who is very approachable and pleasant Danger: Undertrained leaders in remote offices who give bad recommendations Give priority to training the people who are most likely to be asked questions by their peers 16

17 Shared criteria for DITA development Challenge: How to evaluate DITA skills of writers in different teams and locations with different managers? Shared criteria for evaluating writers DITA skills at NetApp 1. Challenged: Unable to work in DITA without significant assistance. 2. Developing: Can generate valid DITA output with occasional assistance. Can develop content that is reusable by other projects if coaching is available. 3. Satisfactory: Can generate correctly coded topic-based content, usually without assistance. 4. Superior: Develops topic-based, easily reusable content. Coaches developing DITA writers. 5. Advisory: Develops content that can be a model to other writers. Drives the development of NetApp DITA standards and models. After initial training, everyone starts at level 2. 17

18 Q&A 18