Rethinking the Assembly Line—How “Documentspaces” Can Energize Team-Based Technical Writing

Home/Publications/Best Practices Newsletter/2004 – Best Practices Newsletter/Rethinking the Assembly Line—How “Documentspaces” Can Energize Team-Based Technical Writing


December 2004

Rethinking the Assembly Line—How “Documentspaces” Can Energize Team-Based Technical Writing

CIDMIconNewsletter Michael Fergusson, Vice President of Product Strategy, Blast Radius

The quintessential innovation of the twentieth century was the assembly line. It was a simple enough principle: keep people still, and bring the materials of work to them. Time was money, and independent thought, creativity, or a “big picture” viewpoint were luxuries sacrificed in the pursuit of efficiency. Despite being somewhat joyless, life on the assembly line ushered in a new era of productivity the world had never seen before.

Today, with few exceptions, we’re still hard-wired to think along straight lines, our collective mental DNA holding fast to the assembly line as the archetype of work. Even the advent of the computer-driven business environment wasn’t enough to break old habits. Consider how we manage documents these days-we think of them as physical entities, materials of work. So, we do what comes naturally. We keep people still and bring the work to them.

No one would expect that a dozen people who need access to a database would each have a copy of the database on their local system. Instead, we would all expect to access a view of the data. Although we understand the notion of a database as a place in which we work to gather insight, we are still stuck on the notion that content is a physical thing to be routed and shared.

The result? We play pass-the-document. Sometimes we wait our turn, and sometimes we all pounce at once. Team-based content creators have almost accepted that a life of endless meetings is simply their lot in life- especially when it comes to many-to-many collaboration. We exchange email chains that seem to have no beginning or end. Documents become tangled messes, riddled with track-changes and comments that are almost impossible to navigate. And in the center of it all is the author, whose unenviable fate is to play the part of air traffic controller.

The task of creating content is more art than science; its authors and contributors more akin to craftspeople than assembly line workers. Craftspeople, like technical writers, work best with a workbench that keeps a complete project in front of them at all times. They may spend a whole day perfecting one small detail and spend the next reconsidering their overall color scheme or technique. They may work in a studio with others and thrive on over-the-shoulder brainstorming.

But despite the parallels between craftspeople and technical writers, the workbench of today’s documentation team remains static and linear, preventing them from working as well as they could.

An Elusive Trinity: Context, Collaboration, Control

A complete trinity of elements must be present for team writing to be made easier: context, collaboration, and control. The outdated methods common today create reviewing silos and flawed processes that may deliver one of these elements, but never all three effectively.

For instance, some methods may make it possible for contributors to work in context but without any input or collaboration from their peer group. These include using word processor and PDF revision marking, an unscalable method that creates version control issues and becomes more unwieldy with every added contributor; or printing and reviewing on paper, the classic bottom-of-the-barrel option for when all else fails.

Other methods enable some form of collaboration but without context and control. These include the dreaded face-to-face meetings, which can be slow, painful, and untrackable exercises in consensus-building; or Web conferencing, instant messaging, or email, channels that are disconnected from the document, making change tracking difficult if not impossible.

Finally, some methods offer a degree of control but at the expense of either collaboration or context. These include using spreadsheets to track comments and changes, which creates additional work, sub-optimal accuracy, and slow turnaround time; document storage systems with a bug tracking system to submit change requests, which forces authors to switch back and forth between disconnected applications; or virtual team rooms and content management systems that attempt version tracking but limit interaction among contributors and cause work to occur out of context.

As go-to-market strategies become more ambitious, deadlines are crunched, product complexity grows, and the pressure for accuracy is heightened. Writing teams do the best they can with an outdated workflow, but until a system that delivers the trinity of context, collaboration, and control is finally discovered, team success (and sanity) is neither easy nor guaranteed.

XML: A Key Tool on the New Collaborative Workbench

The function of creating technical documentation can be one of two things. With outdated methods, writing teams require more time and more resources to get content published. But with the right technology and a more collaboration-savvy approach, a greater volume of high-quality documentation can be produced in a faster timeframe, making it possible for teams to feel a greater sense of ease and confidence in their work. This is where XML comes in.

By design, XML treats text content separately from all the formatting, publishing, and distribution rules that govern it. As a result, organizations can easily repurpose content for different audiences or delivery channels but need only author or update it in one unified, controlled place.

Imagine an aircraft oil pump manufacturer that supplies pumps to 32 different aircraft types. If a service instruction is changed, the documentation for each aircraft must also be changed. With XML-based content creation, the new service procedure is created as a reusable component of information that will appear in the correct place within the documentation for all 32 aircraft, automatically. No one needs to rewrite it 32 times. No one needs to edit and approve it 32 times. No one needs to reformat it 32 times. Since XML can be published easily to multiple formats-print and online-no extra work is required to present the information in any medium. The information is always correct whether it appears in one location or thousands, because it is handled only once by the documentation writers who are officially endorsed as domain experts.

Because of its publishing power, XML is well recognized as the de facto technology foundation for content creation. It brings us a step closer to true collaboration since content in this format becomes more modular and adaptable to new ways of working. Business pressures-such as globalization and the need for regulatory compliance-require organizations to heighten collaboration, prompting a universal shift toward XML as a foundation for creating and managing content.

But if technical writing teams are like craftspeople working together in a studio, XML is only a tool, like the paintbrush. In order to power the kind of collaboration that would make the documentation process more efficient (and enjoyable) for all, we need to reconsider the design of the crafting workbench. In fact, we need to elevate our thinking about the whole team’s working environment. This means complementing the power of XML with a collaborative technology framework-one that finally makes it possible for content professionals to work together more seamlessly.

What’s Standing in the Way of Collaboration?

Computers and software are infinitely usable and quite capable to adapt to how technical writing teams work most optimally-as collaborative craftspeople. But to date, none of the methods touted as “solutions” (word processors, PDF annotations, face-to-face meetings, and so on) have made this ideal possible-even those that aim to leverage XML. Why? Because they still cling to linear, assembly line sensibilities, passing a physical document from contributor to contributor in either serial or broadcast fashion. (See Figure 1.)


Figure 1. Traditional Content Creation-Broadcast Distribution

Those of us who have been either an author or a contributor in a broadcast-inspired model may recognize this as the “everybody pounce at once” way of working.

The author distributes a copy of the source document to everyone. Each reviewer works in parallel and in a silo, with no context or forum for wider debate. Multiple versions abound, which requires intensive, imprecise consolidation by the author with every draft, with great redundancy of effort for all.

Contradicting recommendations and differing opinions are tough to resolve, and when a final document is finally reached, there is high likelihood of misinterpreted feedback and inaccuracies. (See Figure 2.)


Figure 2. Traditional Content Creation-Serial Distribution

Serial distribution lacks the frantic, air-traffic-control feel of broadcast distribution. But if you’ve worked in this linear, “take turns” model, you’ll be familiar with the never-ending bottleneck that results.

Perhaps the most time-consuming of traditional methods, serial distribution attempts to avoid redundancy of effort by passing a document from reviewer to reviewer, each adding comments one-at-a-time instead of in parallel. While this may minimize the versioning issues associated with broadcast distribution, it creates a laborious, time-consuming cycle that the author and reviewers must endure with every draft.

As more people line up to contribute, the distributed file becomes increasingly complex and unwieldy and comments are likely to be lost or misunderstood. By the time it’s returned to the author, the now tangled mess of suggestions doesn’t do any favors for the author or for contributors.

The Documentspaces Revelation

After a great deal of study, my colleagues and I were hit with a revelation that came down to one key word: context. All of the stop-gap methods in vogue share a common weakness: serial or broadcast, they all separate the work of content creation from the content itself.

Our revelation came to life as a technology vision called Documentspaces. Rather than applying a document to a reviewing cycle (which necessitates serial or broadcast distribution), we apply the reviewing environment to the source document. The source document, in essence, becomes the environment in which authors and reviewers work. Participants conduct real-time debates, discussions, and content development in the context of the document itself. The document becomes the meeting room, the master content view, the recording notepad, the debate forum, and the authors’ and contributors’ workbench-all in one. (See Figure 3.)


Figure 3. Documentspaces-Inspired Content Creation

Not Just Collaboration-Contextual Collaboration

Because Documentspaces effectively turns the document into the working environment, there is no need to switch between the document and separate communication tools. This means that collaboration becomes contextual. Teams are not only able to work more seamlessly with each other and the text at hand but are also able to track the evolution of the document at a fine level of detail.

Once we discovered the missing link of context, we set to work, and a platform based on the Documentspaces technology vision was born.

Documentspaces Come to Life

Our implementations of Documentspaces use Dominion, a unique XML middleware platform developed by Blast Radius. Dominion uses a patent-pending protocol based on the XML Document Object Model (DOM) to synchronize change events between a central, shared document stored on the server and multiple remote client copies. Each client has a real-time view of the current state of the shared document and all related artifacts of the collaborative process. Each client works independently, but any change or comment added to the document by one client is immediately seen and responded to by all other clients.

During a review process, two contributors can instantly see that they disagree about a proposed document change, discuss the issue in real-time inside the document, and resolve it on the spot. The issue won’t have to be debated in a post-review meeting or email chain. Similarly, authors and reviewers can track the status of an issue and instantly see what action has been taken on it.

Because Dominion is based on the standard DOM specification, it can work with any authoring environment that supports the DOM, including desktop editors, Web browsers, and collaboration tools. Thus, users can take advantage of the model in a variety of modes, both synchronous (real-time) and asynchronous. For example, they can use a desktop editor in an offline mode, posting their changes and comments when they re-connect to the network. Or, they can engage in real-time updating of a document that is concurrently accessed by multiple other users.

With Documentspaces, collaboration on documents becomes context-rich, because the focus is maintained on the current document; frictionless, because there is no need to switch between your work environment and a separate communication tool; efficient, because a document can be shared among authors and reviewers in real-time; and lossless, because Documentspaces capture the relationships between collaboration artifacts (comments, annotations, suggestions, discussions, and approvals), the documents to which those artifacts relate, and the processes that weave them together.

Documentspaces therefore make it possible for the content creation process to be more efficient, manageable, and auditable for technical writers. It allows authors and reviewers to view and respond to each others’ comments in real-time and in-context, eliminating miscommunication, backtracking, multiple versioning, and process delays.

It is both the craftspeople’s workbench and community studio come to life, marking the era of truly collaborative, in-context, team-based content creation-and the end of the technical writing assembly line.

A Much More Agreeable Moniker…

With a Documentspaces-powered workflow, technical writers get to indulge their natural tendencies to brainstorm, share ideas, and work together while resolving the need to be highly organized and efficient. They focus their energies where they can make the greatest impact, going back to the essence of writing rather than drowning in endless meetings and administrative overhead. Their working days are more streamlined and less cluttered.

In this revitalized model, authors and writing teams need no longer play air traffic controllers or accept their “bottleneck” reputation. Instead, they earn a much more agreeable corporate moniker-that of highly collaborative, timely, and dependable content champions. CIDMIconNewsletter

About the Author