Structured Writing

Mark Baker

• Publisher: XML Press
• Year: 2018
• ISBN:
  9781492070818
• Edition: 1
• Topic: Computer Science
• Subtopic: Computer Science General
• Index: Computer Science

Structured writing has never been more important or more confusing. We keep trying to do more and more with content, but we give ourselves less and less time to do it. Structured content can help keep your rhetoric on track and your processes efficient. But how does it do that and what is the relationship between rhetoric and process? It is easy to get lost in sea of acronyms and buzz words: semantics, XML, metadata, DITA, structure, DocBook, hypertext, Markdown, topics, XSLT, reuse, LaTeX, silos, HTML. Structured Writing cuts through the noise, explaining what structured writing is (you have been doing it all along) and how you can use different structures to achieve different purposes. It focuses on how you can partition and manage the complexity of the content creation process using structured writing techniques to ensure that everything is handled by the person or process with the skills, time, and resources to handle it effectively. Most importantly, this book shows you how the right structured writing techniques can improve the quality of your content and, at the same time, make your content processes more efficient without sacrificing quality for efficiency or vice versa. There are so many options available in the structured writing space today. This book will show you where each of them fits and help you choose the approach that is optimal for your content.

Structured Writing

Mark Baker

Preface

All writing is structured. Writing without grammatical structure would be incomprehensible. All writing software is structured as well. Software that did not produce reliable, consistent data structures would be unreliable and unworkable.

What then does the structured writing community mean by structured writing? As a generality, it means approaches to writing that add a little more structure, over and above the basic requirements of grammar, to exercise some control over the rhetoric or processing of the content. And it also means the use of software that uses more specific data structures, either to support the rhetorical structures of a structured writing method or to support specific writing processes, such as publishing, single sourcing, or content reuse.

So when the industry talks about structure writing methods and tools, it is actually talking about differently structured methods and tools. But you won’t find one agreed definition of structured writing across the industry. Differently structured writing methodologies are often tied to differently structured software tools. This often leads the marketers of these methods and tools to suggest that their particular methodology or tool is the very essence and definition of structured writing. Some definitions see it as a writing method with no software component at all. Others identify it with a single software tool or standard.

This often leads people who see no virtue in these particular methods or tools, or who have had an unsatisfactory experience with them, to conclude that structured writing is bunk, or at very least that it is not for them, for their content, or for their company.

The truth is, it’s all structured writing. Even the mainstream word processors and desktop publishing tools you use every day are structured writing tools. But not all structured writing methods and tools are equally effective for individual organizations. There are many ways to structure both the rhetoric and the process of creating content, and one of these may be vastly more productive for you and your organization than what you are doing now.

The purpose of this book is to present structured writing as a whole, to take a step back from the specific structures of individual tools and systems and show that all structured writing approaches share a few basic principles and operations. Understanding those principles and operations will help you choose the structured writing approach that is optimal for your content and your organization.

Whether you are considering a move to a differently structured writing system or trying to figure out why the one you have already implemented is not working as well as you hoped, this book will help you figure out how structured writing works, what is possible, and what is not possible, and it will help you figure out which techniques, structures, processes, and tools are going to work best for you.

In the age of the web, organizations produce and deliver ever more content on ever shorter deadlines. To keep up and maintain quality, they need tools and techniques that support rapid and reliable delivery of consistent, high-quality rhetoric. Many organizations are turning to structured writing solutions (that is differently structured solutions) to keep up and meet demand. However, without a clear and comprehensive understanding of what is possible, they often choose solutions that are sub-optimal or even worse than what they were doing before.

I have been in the structured writing industry for nearly 25 years. In that time I have worked with and designed structured writing systems that improved both process and rhetoric. I have also built tools and systems myself (some of which I will talk about in this book), because I have often felt that existing approaches did not do enough to balance the demands of process and rhetoric or to fully exploit the capacity of structured writing to promote both.

One of the things I have learned over my career is just how much our minds tend to follow the ruts laid down by our familiar tools and processes. I can’t count the number of requirements documents I have read over the years that insisted that any new system must work exactly like the old system in almost every particular. I don’t believe this is so much a reluctance to change as simply a difficulty imagining how things can be done differently. Making sure that a new system does everything you need often means specifying that it does everything the way you are doing it now.

Every tool encapsulates a methodology – a set of choices about how problems should be partitioned and addressed. This can lead people using a particular tool to view that tool’s methodology as if it were the methodology of the craft itself, rather than simply one set of choices about how problems should be partitioned and addressed. Thus, individual tools create ruts in the mind, constraining our ideas about how things could be done.

By separating the principles and practices of structured writing from the implementations of particular tools, this book seeks to break out of the ruts created by particular tools, so you can see how to accomplish your objectives using these basic principles and practices before you select or build a tool set to implement those principles and practices in your organization.

It has been my particular privilege and opportunity to work with some of those rare people whose minds seem to be immune to such ruts and who were able to jog me out of my own ruts and help me see how different approaches could be both simpler and more effective. To name a dozen would be to neglect a score, but one name in particular deserves mention: Sam Wilmott, principal architect of the OmniMark programming language and all round markup language savant. Sam taught me to see the relationship of text and algorithms in a fundamentally new light, and everything I have done in my career leading up to writing this book has been working out the implications of what I learned from Sam. The SAM markup language I use for most of the examples in this book is an homage to Sam, and not just in its name.

Introduction

There are only six reasons for an organization to create content:

• To meet regulatory requirements
• To ensure the correct performance of internal processes
• To generate leads and support the sales process
• To lobby governments and affect social and political trends
• To improve customer retention through post-sales support
• To deliver content as a product in its own right

Each of these goes straight to the bottom line of revenue and profitability, and each depends directly on the quality of content. To create a content process with any goal in mind other than to maximize content quality is foolish, shortsighted, and almost certainly guaranteed to have negative effects on revenue and profitability even if it reduces costs in a particular division.

Rhetoric is the way in which content works to meet its goals. Each of the content goals outlined above requires a specific approach to rhetoric to make sure it does the job it is supposed to do. At the same time, like any business function, the creation of content needs to be done efficiently, and it needs to meet its deadlines. To achieve your business goals, you need great rhetoric and efficient processes.

1. Rhetoric

Aristotle defined rhetoric as “the faculty of observing in any given case the available means of persuasion.” To put it another way, rhetoric is figuring out what to say and how to say it to persuade, inform, entertain, or enable the reader to act.

The word rhetoric is sometimes used dismissively, to describe content that is hollow or empty of meaning: “mere rhetoric.” And content can use rhetorical tricks yet entirely lack substance. However, if there can be mere rhetoric there can also be substantive rhetoric, and if you want to communicate your substance effectively, you need sound rhetoric. Rhetoric without substance lacks value. Substance without rhetoric hides value. Substance plus rhetoric unlocks value.

Rhetoric takes many forms. In some cases it is a matter of choosing the right metaphor to communicate a particular point, or the right word to trigger an emotional reaction. But there are more mundane aspects to rhetoric, such as making sure you give the right information, use the right terms, and organize and label content so that people find what they need. These aspects are just as essential to persuading, informing, entertaining, or enabling the reader to act. They are just as much part of rhetoric as le mot juste or the striking metaphor.

These more mundane aspects of rhetoric are often quite structured, which means that they are more or less repeatable. If something is structured, it conforms to some shape or set of rules that you can observe, define, and reproduce independent of the particular instance. This means that you can create multiple instances of those things that all conform to the same structure.

A house is made of a particular set of bricks, but the bricks are put together according to an architectural plan. You can create a new house next door using the same architectural plan but different bricks. A recipe is made of particular words, but those words are organized according to a rhetorical plan. You can create a new recipe on the next page using the same rhetorical plan but different words, describing a different dish. Structured writing, in the purely rhetorical sense of the word, means capturing, defining, and implementing repeatable rhetorical structures.

2. Process

This ability to repeat structure is at the heart of process in any field. A process finds and defines the most efficient way to do something, which is pointless unless you plan to do the same thing more than once. Writing down how to do something you never plan to do again would serve no purpose.

Process is all about repetition. A process that aims to produce rhetoric is fundamentally concerned with the repeatability of rhetoric. Thus process and rhetoric are intimately combined in the production of content. Structured writing holds the key to repeatability in rhetoric and process.

Too often, however, structured writing systems and implementations focus on process issues alone, leaving rhetoric to take care of itself. There are three problems with this approach:

• Creating effective rhetoric is a complex task requiring the whole of the writer’s attention. Yet many tools designed to support process goals such as publishing and reuse introduce complex tasks and concepts that pull attention away from the rhetoric that ought to be a writer’s chief concern. This book shows how you can remove most of these distractions from writers.
• Some of the structures and processes enforced to meet process goals can be harmful to rhetoric. Although they may make the process more efficient, they can prevent writers from producing the best rhe...