Two Strategies for Implementing Structured Writing in Collaborative Technical Writing Environments
Structured writing seems to be the most logical strategy for collaborative writing. There are many advantages to structured writing: besides facilitating collaborative writing, structured writing enables the reuse of information chunks and meets the requirements of XML perfectly. Why then, do we find only a minority of technical writers working in a highly structured environment? One reason is that technical communication and documentation are moving from externally used information (outbound) to internally used information (inbound). Outbound and inbound technical communication require very different strategies for document generation and management. Outbound communication requires a content-management strategy; inbound communication requires a knowledge-management strategy. Both strategies can benefit from a structured writing approach. However, depending on the environment, you have to implement the structured writing method differently. In a content-management environment, you should implement the structured writing method top-down. In a knowledge-management environment, you should implement the structured writing method bottom-up. (See the table below.)
What Is Structured Writing?
Structured writing is a method that restricts the structure of information and allowed information elements, such as specific tables, plain text, bulleted lists, numbered lists, and specific graphics, for a community of writers.
Although structured writing is often associated with collaborative writing environments, individual writers can also benefit from it. For lone writers, structured writing brings in more consistency, a flat and accessible structure, and a focus on content rather than on presentation. Structured writing is an obvious choice for collaborative writing because it enables single sourcing and the reuse of document chunks. Structured writing is the only workable option for database publishing, Web publishing, and publishing on all kinds of constrained displays such as WAP-enabled mobile phones and PDAs.
From Outbound to Inbound Technical Communication
The figure below illustrates the process of outbound technical communication. Manufacturers of the product (equipment or software) supply the customer with the product and the documentation. The documentation helps the customer use the product effectively and efficiently.
Figure 1: Outbound Technical Communication: The manufacturer supplies the product and the manual.
This process has long been viewed as the only effective way to convey technical and user information. However, the situation has changed dramatically over the past decade. The profit margins on equipment and software sales are eroding due to competition. Manufacturers need more revenue generators than just the initial product sale. Upgrades, consulting, and service contracts have become just as profitable and, in some cases, more profitable than the initial product sale.
Additionally, the complexity and modularity of technology products requires increasing specialization. Traditional documentation, such as manuals and online help, has become insufficient to meet customer needs. Instead, service has evolved from fixing bugs to providing
- professional services such as IS outsourcing
- delivery of help desk and first- and second-level support
- auditing, network consultancy, and support
- business advisory services
- risk management
- training and education
As a consequence of this business evolution, manufacturers do not transfer technical information about the product directly to the customer but instead to their own consulting, service, and help desk staff. These consultants tell the customer how to work with the equipment or the software.
Where do consultants receive their information? Not from structured glossy user manuals but from a mix of unstructured sources: memos, emails, databases, help desk systems, presentation slides, their own experience, and talking to colleagues.
The figure below represents the inbound technical information flow. Service engineers and consultants bridge the inbound part and the outbound part of technical communication. It goes without saying that outbound and inbound technical communication are very different ways of communicating. Let us compare them and try to develop an appropriate implementation for both of them.
Figure 2: Inbound Technical Communication: Consultants gather information from unstructured sources, and they tell the customer how to use the product.
Content Management Versus Knowledge Management
Outbound and inbound technical communication require different strategies: content management and knowledge management, respectively. For the sake of simplicity, I represent content management and knowledge management as two ends of a scale. The reality will always be somewhere in between or a blend of both worlds. The figure below shows the conceptual space between content management and knowledge management. The content-management icon reflects the one-way communication of a limited number of writers to a large audience, facilitated by a document-management system. The knowledge-management icon represents a process where everybody is a writer and a reader, interacting with an intranet portal.
Figure 3: Content Management and Knowledge Management: Two ends of a scale
In a content-management strategy, writers produce highly structured information. The documents are validated against a DTD and stored in a repository. The repository is a large database that contains the documents and the meta-information. Eventually a publication manager, who publishes documentation based on content plans and information chunks in the repository, assembles the documentation set. In some cases, the documentation manager is a machine that automatically assembles a manual based on the product options and the reader profile.
This strategy features a highly structured approach. It encompasses all of the modern trends in documentation: collaborative writing, single sourcing, and extensive use of meta-information.
Figure 4: Content Management: Documentation is developed through a workflow that is formalized in a content-management system.
In a knowledge-management model, content contributors are content users as well (see the first figure below). They communicate and interact using a variety of (possibly structured) document types. The main technology in place is a portal server, such as Microsoft SharePoint Portal Server, Oracle 9i Portal, IBM WebSphere Portal, or iPlanet Portal Server. The eventual aim is not publishing but GATA: Give Away, Take Away. The system does not impose the use of meta-information. It allows for meta-information, but writers are not likely to apply it in all cases. Because the intelligence is not in the document in the form of meta-information, it must be in the system. Indeed, intranet portal servers feature advanced automatic indexing and search mechanisms based on artificial intelligence. When executing a search, the systems can take the preferences of the individual readers into account. (See the second figure below.)
Figure 5: Knowledge Management: Readers and writers interact through an intranet portal, giving and taking information away.
Figure 6: Typical Screen of an Intranet Portal: There are a variety of document types. The rating reflects the relevance of the document for a given reader. Besides documents, the portal contains discussion lists, FAQs, news, coach information, and reading programs for specific readers. The structure is flat. The search function of the portal retrieves relevant documents based on the reader’s profile.
Content-management and knowledge-management strategies require different corporate cultures. In the table below, I detail the differences between a content-management and a knowledge-management culture. When looking at the table, please remember that content management and knowledge management are two extremes, two ends of a scale.
Your culture (content management or knowledge management) will influence who will write content and how writing will occur.
Implementing a Writing Method
Successfully implementing a writing method will depend on the acceptance of the writers. If they do not like the method, you can forget trying to enforce it. A writing method should fit within the culture of the writers’ group. In the table below, we demonstrate that content-management and knowledge-management strategies are tightly linked to a specific cultural setting. A structured writing method will fit in both cultures, provided the way you implement it also fits in the culture. Let us analyse how the distinction will influence content writing methods. (See the table below.)
The distinction between content management and knowledge management also allows us to say something about the tools that need to be deployed. (See the table below.)
Mixed Environments, Blended Solutions
I have stressed several times that the content-management and knowledge-management models are at two extremes of one scale. In reality, you are likely to come across a mixed environment. Think about a documentation department: the content-management strategy will prevail. But the documentation department has many links with research and development that is knowledge-intensive by nature. Ideally, both departments will use the same structured writing method. Subject-matter experts in research and development, for example, can provide structured information chunks such as process tables and procedure tables. These chunks are further edited by technical communicators and assembled into larger documents that are published on paper, as online help, or as Web pages. A structured writing method allows for genuine single sourcing, not only by technically implementing single sourcing but also by leveraging the technical knowledge of subject-matter experts.
Some Ideas for Implementation
Summarising, I would like to suggest two scenarios: one for implementing structured writing in a content-management environment and the other in a knowledge-management environment.
If your technical communication is outbound, then you are managing content rather than knowledge. You are likely to have a team of professional communicators who write structured documentation for a large audience. To implement a content-management strategy, you will need to implement structured writing and a content-management system. Writing with structure will require a top-down approach. You’ll have to make a value proposition and present it as high as possible in your corporate hierarchy. Study the basics of XML and team up with a consultant who has XML and structured writing experience.
Once the content-management decision is made, identify a pilot project. The pilot project may be a subset of the regular documentation. The pilot project has two purposes: to test material for the system and to provide training for the writers. All the writers will have to be trained in the structured writing method. You may want to seek a consultancy to set up the entire structure of the documentation and the meta-information.
If your technical communication is mostly inbound, then you will benefit from a knowledge-management strategy. Managing knowledge requires a bottom-up content structure. Let writers or writer communities decide whether they are going to use a structured writing method or not. Selecting a pilot project will be difficult because people in a knowledge-management environment usually write short, unstructured documents. You can better identify some key persons in a department, people who are intent on communicating, writing, and documenting. Let them experiment with a structured writing method and let them “spread the word” if they like it.
If there is budget for a system, consider an intranet portal. The cost will be more than ten times lower than the cost of a content-management system. Let the writers stay with their favourite tools, such as MS Word and PowerPoint, but provide them with templates for the most frequently produced documents.
You might not need consultants to implement a knowledge-management system, but some of your writers might need individual coaching to use the method. Request a communication or an organisation specialist as a consultant.
About the Author