Collaborative authoring in DITA

Editor's Notes

• #2: I titled my presentation “Collaborative Authoring in DITA, or, How We All Learned to Share”. It might seem funny to talk about sharing in a webinar about content ownership, but it is ownership that makes sharing possible. Let’s see how.
• #3: First, let me give a a quick intro to NetApp. We’re a big company now, with 3 ½ billion in revenue and 8000 employees around the world. NOT FOR WEBINAR: I like to point out, at least to my boss, that this graph starts when I joined the company. Not like there’s a definite correlation or anything. Ha ha.
• #4: What do we do? We make storage systems. Our customers store and manage all kinds of data using our products, from all the data needed to render the movie “Avatar” to more mundane things, like all of Yahoo Mail. This slide is straight from NetApp Marketing—and their message about NetApp products parallels our journey in content. Instead of building different solutions for each storage problem, NetApp has a unified platform. You can leverage the same hardware, software, processes, and learning across all the different areas. In Marketing’s own words: “Learn Once, Deploy Everywhere”. Their theme parallels what we do in Information Engineering—we look for efficiencies by writing content once, using it everywhere. TRANSITION: But before DITA, we couldn’t reuse content like that. We were still using content authoring methods right out of the 90s.
• #5: Image source: Wikipedia 1790s, practically. Here’s a tech writer from the 1790s, using the “iPad” of his day, this one with the fancy “quill” interface. Things weren’t really that much different for us back in the pre-DITA days. Before DITA, we were writing in unstructured Framemaker, and each book would be lovingly hand-crafted, start to finish, by a single writer. The content written for that book would be used only in that book. You might reuse information over successive releases of the same book but that’s about it. Also, writing groups would focus on the output format they were publishing to: if online help was the primary deliverable, they would all write in Robohelp. If a printed manual was the primary deliverable, Framemaker was their tool. NOT FOR WEBINAR: This guy is almost from the 80s—witness the wide lapels and shoulder pads on this guy’s suit jacket. All he needs is a power tie.
• #6: Image source: www.netapp.com and dita.oasis.org Now we’re using DITA. And we finally can apply another idea from the 1790s to content. In 1798 Eli Whitney dumped a pile of parts on a table and, just picking parts at random, proceeded to put together a working musket. It was a tremendous breakthrough: No longer did a single craftsman have to create the deliverable from start to finish—by using interchangeable parts, you could divide the work across multiple people. With DITA, you can build more than one output format from the pile of parts. It’s as if from that same pile of parts, Eli Whitney built a musket, a dishwasher, and a space shuttle. From the same repository of DITA topics, you can build a printed manual, online help, slides for a training class. Even better, DITA takes this even further: The same part, a content topic, can be in two places at once. It’s the rules and structure of DITA that allows this reuse of content.
• #7: If writers don’t own all the content for a book anymore, what do they own? Well, the job role expands: writers own relationships and technologies. A writer is a key member of a development team. At NetApp, often the primary developers for a product feature are in one location, and the writer there owns the relationship with that team. The writer also becomes the knowledge expert for a technology or feature set. So the concept of Data Protection, because it’s understood so well by one writer, is documented by that writer, and the resulting content is used across all the different deliverables that need to discuss Data Protection. Each writer, then, owns the topics that document a particular technology or the product of a particular team of SMEs.
• #8: If these deliverables span multiple authors, how do you put it all together? You need Component Content Management. You just can’t do it in the filesystem. For us, we have writers from all geos contributing to the same deliverable. How it works: Topic owners check their content topics into the Trisoft repository in Sunnyvale. These topics are written and edited in their respective offices, reviewed by the SMEs working with that topic owner, then made available for reuse across any NetApp deliverable.
• #9: Writers manage the topics they’re working on with submaps. Submaps are small DITA maps that group the topics for a specific subject area, writer, or review group. Makes it easy to manage groups of topics; for example, for reviewing, or even for reuse—just include the whole submap of topics as they together talk about one specific feature or functionality.
• #10: The deliverable is owned by a Publication Captain—a writer who coordinates the work of the other contributors, keeps track of the handoff schedule, and often writes a lot of the content too. Publication Captain owns the master map and final handoff to production. The “Master Map” defines the deliverable—just a DITAmap that topicrefs the submaps into a contiguous whole. Trisoft conveniently wraps all this up in a construct they call a “Publication”. These submaps, of course, reference Universal Topics—topics we know to be production ready. Such topics can be thought of as the Gold Standard—they’ve been reviewed, often tested, and we can trust the content to be usable everywhere. From the Publication then you can build different output formats. TRANSITION: But how do you know whether a topic is the Gold Standard? If you’re reusing someone else’s work in your deliverable, how do you make sure it’s ready?
• #11: You could just pick up the phone and call the other topic owners. We use a lot of Voice-over-IP at NetApp; this picture is Voice-Over-Tin-Can. But this is not really practical in cross-global, cross-timezone collaboration. Synchronous communication, like telephone, IM, or meetings can’t scale globally. Even email or discussion communities can’t work for the amount of content you need to manage. Hundreds of topics. Can’t go, for every one of the ~500 topics in your deliverable, “ok, is this one ready? How ‘bout this one? Did you get this one edited?” and repeat that with all 15 or so of the topic owners contributing to the effort.
• #12: This is where workflow states in the CMS make life much easier. The workflow states tell you the status of the content. In our CMS, you just click a button to get the Publication Report, which tells you what’s going on with all the objects in the deliverable. Oh, I see these are still being worked on! (state = “Draft”). Here’s some that are not ready for prime time at all (state = “Under construction”). Using the Publication Report, I can tell if topics are being reviewed, or if they’re absolutely ready for me to pick up and reuse in my deliverable (state =“Production Released”) TRANSITION: The workflow states make it easier to know about content readiness. But you need a solid process specification at a lower level to allow all the parts to fit together.
• #13: Even DITA’s built-in structure, while it enables reuse, isn’t enough to make reuse work. You need to enforce your style guide and content guidelines. We have editors for each writing group to ensure a consistent voice—DITA does some of that with its built-in structure, but you still need eyes on words. Tools can help—We use Author Assistant as a “power” style guide. We put our rules from the printed style guide in there and Author Assistant flags text as people write. Also, everyone across the world needs to use the same metadata model, condition values, and reusable components. Reuse of content smaller than a topic, using DITA’s conref mechanism or Trisoft’s own Variables, is controlled through “libraries”. And these libraries are owned by specific people. Project-specific libraries are owned by a designated person in that writing group. Corporate phrase library is owned by a senior editor. Conditions also need to be centrally managed—if someone slips in their own condition label into their topic, and you reuse it, how do you know what to do? Should I turn this text on or off? We’re lucky to have a brilliant senior writer that takes care of this—the CMS actually has a software client for this task, called “Condition Manager”, and this lady, who we dub the “Condition Maven” manages all conditions through that tool.
• #14: TRANSITION: Because these process decisions and rules affect everyone, you need governing bodies that can make these decisions. We have two core teams, made up of representatives from each writing group, editorial, and tools, to make these global policies: one team that is Content Architecture focused, and one that is focused on Tools and Technology. Having a representative democracy means everyone gets a voice, and you cover all the possible issues—reps can bring up their constituents’ particular corner cases. Also, decisions get buy-in because every group’s rep has a part in the discussion.
• #15: Finally: The most important thing to make this work, and that is something that you can’t code into a tool, is TRUST. Is the content in this topic good enough for me to reuse in my deliverable? Did that topic’s writer test the command options he has there in the Lab? Are all the comments from reviewers and editors fixed? If the topic is “Production Released” in the CMS, I can trust it and reuse it. When writers “take ownership” of their work, meaning taking responsibility for their topics, you can trust the content.