Two Strategies for Implementing Structured Writing in Collaborative Technical Writing Environments

Home/Publications/Best Practices Newsletter/2002 – Best Practices Newsletter/Two Strategies for Implementing Structured Writing in Collaborative Technical Writing Environments

CIDM

February 2002


Two Strategies for Implementing Structured Writing in Collaborative Technical Writing Environments


CIDMIconNewsletter Luc Bouquet, General Manager, ATEK

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.)

A Structured Writing Approach

Outbound Communication

Inbound Communication

Document Strategy

Content management

Knowledge management

Implementation

Top-down

Bottom-up

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

Outbound
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.

docextern17

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

Inbound
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.

docintern50

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.

extrem11

Figure 3: Content Management and Knowledge Management: Two ends of a scale

Content Management

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.

contentman13

Figure 4: Content Management: Documentation is developed through a workflow that is formalized in a content-management system.

Knowledge Management

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.)

knowledge28

Figure 5: Knowledge Management: Readers and writers interact through an intranet portal, giving and taking information away.

learning-square14

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.

A Comparison

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.

Differences Between a Content-Management and a Knowledge-Management Culture

Content-Management Culture

Knowledge-Management Culture

Hierarchical organisation

Decisions are made on the highest level. Documents have a specific purpose and need to be validated.

Democratic organisation

Writers are peers who share documents and information.

Top-down structure

The structure of the documents is fixed. The decision to use Information Mapping or any other structured writing approach is made by the management.

Bottom-up structure

Individual writers decide for themselves whether or not to use a form of structured writing.

Writers are professionals

The complexity of the tools and of the subject requires professional and skilled technical writers.

Writers are also readers

Writers and readers are subject-matter experts. They may have acquired writing skills, but writing is not their main concern.

High-level decisions

The structure of the documentation is decided upon by specialists and formally described in a Document Type Definition or a Schema.

The tools are selected after thorough evaluation.

Personal decision

Writers may decide by themselves on the structure of their document, on the writing method if any, and on the tools. Some use MS Word; others use PowerPoint or even Excel.

Obligation

Once the decision is made and the system installed, the writers have to use the same structured writing method.

Conviction

Writers may decide for themselves to use a form of structured writing. If the method proves to be effective, other writers will automatically want to use it.

Rigidity

It is hard to change the system. Any change in the structure of the document or in the method affects the whole system and will be made reluctantly.

Flexibility

Writers are responsible for their own documents.

Traditional industry

Content management is found in environments where the products are clearly defined and where there is a tradition of documentation, e.g., banking, automotive, aeronautics.

High-tech, advanced services, new enterprises

Knowledge management is found in environments where the product is being defined and developed every day, e.g., consultancy firms, service companies, and start-ups.

Reuse of information chunks

Reuse of information chunks is encouraged. It involves the risk that a bad chunk with incorrect or obsolete information remains in the “food chain.”

Self-regenerating capability

Writers and readers give away and take away. They use chunks from one another and modify them to their own taste.

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.)

Content-management and knowledge-management strategies are tightly linked to a specifc culture.

Content-Management Culture

Knowledge-Management Culture

One long decision process

Hundreds of meetings to weigh the pros and cons precede the decision to implement a structured writing method and the content-management system.

Several short decision cycles

Individuals or small communities may decide for themselves whether or not to implement any form of structured writing.

High investment at once

The investment can be huge. The technology cost includes the system and the customisation. Another important cost is training and consultancy for writers.

Gradually increasing investment

The investment gradually increases as writers “convert” to the method in relatively small numbers.

Start by selecting a pilot project

Everybody knows well in advance what kind of documents will be produced. Therefore, it is relatively easy to select a pilot project. The pilot project serves to test the content-management system.

Start by selecting key users

You can better identify some key users. These are writers who are already intent on using a structured writing method. They can convince the others, mainly by writing documents that make a difference.

Writers are professionals

You will need a team of professional writers, clearly distinguished from the readers. The readers may include knowledge workers as well as factory workers.

Everybody is a writer

Everybody is a knowledge worker; that is, everybody is supposed to be able to write and read and to access the portal.

Approval cycles

A workflow and document flow analysis will precede the implementation of the system. The workflow with approval cycles will be partially automated with the system.

Discussion cycles

As writers and readers give away and take away information, informal discussion cycles will automatically emerge.

Distribution

A few writers write for a large group of readers. Any time gained because the documents are readable and accessible must be multiplied by the number of readers, which in turn justifies the high investment.

Give away take away

Documentation is a side effect, not the main product. Time gain cannot be invoked to justify high investments.

The Tools Needed for Content Management and Knowledge Management

Content Management

Knowledge Management

Content/document-management system

A document-management system or a content-management system is needed. The system needs to provide database, workflow, and publishing functionality. Context management is an interesting additional feature. XML is on its way to becoming the industry standard.

Intranet portal

Intranet portals have the required flexibility and the artificial intelligence that compensates for the lack of meta-information. The cost is relatively low.

Controlled language tools

Controlled language will ensure consistency and translatability of the documentation.

Peer review

Writers are encouraged to have their documents peer reviewed.

Specialised

Specialised tools for the writers include FrameMaker and Epic. In many cases, the tools will be selected for their XML functionality. Because translation might be an issue, translation memory and machine translation are often needed.

Graphics include vector and 3D graphics.

Standard

In this environment, you will find the standard office tools such as MS Word, Excel, and PowerPoint.

Graphics are mainly Excel charts or diagrams made with tools such as Visio. Illustrations are mostly clipart.

Customisation

Customising the system forms an important part of the implementation cost. A structured writing method, however, will substantially decrease the need for customisation because there are a limited number of clearly defined presentation modes.

Off-the-shelf products

You can develop standard templates to support the writing method.

Information Mapping’s “Formatting Solutions Pro” is a template that supports the use of the Information Mapping method for MS Word users. It includes a wizard that contains more than 20 models for the most common business documents.

Valid XML

Writers need to validate their documents against a DTD. With a structured writing method, you need only one DTD that will fit all types of documents.

Well-formed XML

XML, if any, needs only to be well formed. XML may become the standard for document formats in the future. By then, it will be transparent for the user.

The Tools

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.

Content management
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.

Knowledge management
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. CIDMIconNewsletter

About the Author

BPFebruary02a5

We use cookies to monitor the traffic on this web site in order to provide the best experience possible. By continuing to use this site you are consenting to this practice. | Close