By Mark Baker | Member
For the technical writer encountering it for the first time, Agile may look like just another project management methodology. Writers often find themselves assigned to Scrum teams and attending daily standup meetings. They may not be exposed to, or even aware of, the much deeper changes that have taken place—or should have taken place—in the development organization.
The principles of Agile development include:
- Our highest priority is to satisfy the customer through early and continuous delivery of valuable software.
- Welcome changing requirements, even late in development. Agile processes harness change for the customer's competitive advantage.
Achieving these goals requires a much more profound change than merely creating shorter development cycles. To deliver working software early and continuously, and to welcome change late in the development cycle, requires a different approach to designing and building software.
As the authors of Service Oriented Architecture For Dummies explain, traditional software systems had a common flaw:
They weren't designed for substantive change. One pervasive characteristic that makes … applications especially brittle—prone to break easily—is the extent to which the various programs that constitute the software applications are intertwined. These programs depend upon each other for little bits of code; and without such bits, they can't run.
To meet its basic goals, Agile needs to create software that is designed for substantive change. An Agile approach to technical communication should have similar goals and similar principles. To achieve this, it will need to create content that is designed for early and continuous delivery and for substantive change.
Tight cohesion and loose coupling are two of the most important principles used to build software that can be changed easily. An object is tightly cohesive if it is self-contained and handles its main functions internally. It is loosely coupled if it does not depend directly on the behavior of other objects to function. Jigsaw puzzle pieces are loosely cohesive and tightly coupled. Lego blocks are tightly cohesive and loosely coupled.
Loose coupling has become essential to software development on the Web. As Forrester notes:
Amazon.com and its web-native cousins are the envy of many traditional organizations feeling pressure from competitors that innovate more rapidly. What's the critical enabler for rapid software releases? They require loose coupling of components and services, both within and between applications.
Indeed, the reason many companies are moving to Agile is so they can keep up with the rapid pace of software development and deployment required in a networked world.
The Web is also driving us into a world of loosely coupled content. In fact, the very word Web reflects the tenuous threads that connect content on the Web. The Web's great information sources from, Wikipedia to StackOverflow to Amazon, are not organized in rigid hierarchies but through the loose connections of links, likes, tags, votes, filters, and searches.
For loose-coupling to work, you need the individual components to have a high level of cohesion. Pete Goodliffe writes:
Cohesion is a measure of how related functionality is gathered together and how well the parts inside a module work as a whole. Cohesion is the glue holding a module together…. Each module must have a clearly defined role, and not be a grab-bag of unrelated functionality.
If components do not have cohesion, they start to rely on each other in irregular and complex ways. In doing so, they become tightly coupled to each other. You cannot change one without compromising the functionality of another. And thus the ability to change the system quickly and substantially is lost.
Unfortunately, traditional technical communication deliverables and tools are loosely cohesive and tightly coupled. A typical manual, for instance, tends to have a tight coupling between its chapters and sections, but dive into an individual page and you will often find it is not cohesive. Rather than being self-contained and doing one thing really well, it is often hard to understand by itself and depends on what has come before and what comes after. Implementing substantive change in such a manual at short notice is almost impossible.
Tools also tend to encourage the model of a single deliverable organized in a single hierarchy: a tightly coupled model that is hard to change. Even tools that are intended to encourage topic-based writing often tightly couple those topics into specific structures that are hard to change without breaking other relationships.
The forces that are driving development toward Agile are affecting technical communication just as much as development. Readers in a networked, mobile, always-on world expect instant, up-to-date answers about products that are constantly changing and updating. We need documentation designs and architectures that are capable of substantive change in response to new demands. Going Agile, therefore, is something technical communicators should be doing independent of the development team's decision to do so.
To do this, we need to create content in which individual topics are highly cohesive and information collections are loosely coupled. Nicholas C. Zakas writes:
Loose coupling is achieved when you're able to make changes to a single component without making changes to other components. Loose coupling is essential to the maintainability of large systems for which more than one person is responsible for the development and maintenance of code. You absolutely want developers to be able to make changes in one area of the code without breaking what other developers are doing in a different area of code.
Substitute "topic" for "component", "writer" for "developer", and "documentation" for "code" and this accurately describes what we need to do to maintain large documentation sets in a rapidly changing environment. To implement truly Agile technical communication, it is not enough to implement Scrum and stand-up meetings. We need documentation designs and systems that are loosely coupled and tightly cohesive.
How do we produce technical communication that is highly cohesive and loosely coupled? The answer, of course, is topic-based writing. But not all approaches to topic-based writing produce tight cohesion and loose coupling. Achieving these things requires a specific approach to topics that I call Every Page is Page One.
Increasingly, search is the primary means by which people find content. Social media also play a significant role, with people asking for help on forums and in social networks. Even when your content is not online, people bring their Web-trained information finding habits to your content, and go straight for the search box.
Whether people find your content through search or social media, they don't land on your table of contents; they land on an individual page. How well that page works for the reader will depend on how internally cohesive that individual page is. If that page depends heavily on other content, the reader will quickly become frustrated.
This preference for small highly cohesive units of content mirrors what we have seen in the software world, where small cohesive apps and software-as-a-service have replaced monolithic desktop applications with the Web providing the glue that—loosely—couples them together.
To create an Agile technical communication process—one that can keep up with the demands and the pace of change, and that can harmonize with development's Agile process—requires us to create content as small, highly cohesive units that are loosely coupled. Happily, that is exactly the sort of content that works best for the new ways people seek and use content.
Principles that Ensure Cohesion
The Every Page Is Page One information design pattern is intended to help you create content with high cohesion and loose coupling—content the works with the way people seek and use content today. In my book, Every Page Is Page One: Topic-Based Writing for Technical Communication and the Web, I describe the seven principles of Every Page Is Page One information design. The first four deal mostly with cohesion. They are:
A topic should be self-contained. It should do one thing for the reader, do it thoroughly, and do it well. For instance, a recipe is an Every Page Is Page One topic that contains everything a cook needs to prepare exactly one dish. If you are creating a recipe book, testing each recipe with diners will certainly lead to a better book—exactly the early and often user testing that Agile advocates. Also because recipes are self-contained, a failed recipe can be dropped from the book without affecting the overall book, requiring changes to other recipes, or delaying the project.
A topic should have a specific and limited purpose. It should serve a specific and well-defined reader need, and should not contain content that is not essential to that purpose. For instance, a recipe does not attempt to teach you basic cooking techniques. It focuses on the specific and limited purpose of preparing one dish. Defining a specific and limited purpose for each topic is the foundation of the discipline that keeps your topics cohesive and loosely coupled. Think of this definition as the user story that drives and defines your topic.
But be careful not to fall into the trap of simply documenting development's user stories.
Developers' user stories are sometimes more machine-oriented than business-oriented. Your topics may need to do more to help users bridge the gap between business needs and product features. Write your own user stories that define the specific and limited purpose topics must serve for the user.
A topic should establish its own context. It should not depend on the reader having reached it by following a table of contents or reading in sequence. It should be written as if it were the first topic the reader sees. It must make sure the reader knows exactly where they are and what the topic can do for them.
Look at almost any topic on Wikipedia and you will find that the opening sentences (and often the data sidebar as well) focus on locating the subject in time and space. This lets the reader know clearly where they have landed. A topic that establishes its own context cannot be broken when another topic is changed or removed. This allows you to make changes rapidly and with confidence when the product changes.
A topic should conform to a well-defined type. Topics that do one thing and do it thoroughly tend to have the same content and largely in the same order. The specific and limited purpose of the topic leads naturally to its specific topic type. Recipes, of course, conform to a well-known type. But look at short content on all kinds of subjects and you will find the same thing. The same kind of content is treated very much in the same way: similar fields, similarly expressed, in a similar order.
Having well-defined topic types helps to keep your topics cohesive by ensuring that they do the job they are supposed to do. It helps you develop topics faster, because it reuses design patterns and tells you exactly what needs to said in each case. It can also help with iterative or collaborative development, with different elements of the topic being created at different times or by different people.
Principles that Ensure Loose Coupling
The final three Every Page is Page One principles deal mostly with loose coupling. Even the most cohesive topic is not going to meet every reader's needs completely, if only because readers often don't have all the background knowledge and experience they need to comprehend the task they are attempting. These readers will need to find other topics to fully understand their task. But each reader will need different topics and in a different order.
A loosely-coupled topic set does not impose a single reading order on all readers. It supports readers in choosing their own path through the content, secure in the knowledge that whatever topic they read next will work for them as a standalone topic in its own right—because all of the individual topics have a high degree of cohesion.
The principles that ensure loose coupling are:
A topic should assume the reader is qualified. A cohesive topic is written for a well-defined reader and assumes that its reader meets that definition. Imagine a recipe book in which every recipe told you how to whisk, crack an egg, or boil water. Every recipe would be 30 pages long and impossible to use. A recipe is written for someone who knows how to cook. But if you need to know how to do a basic cooking technique, like sweating onions, a quick Web search will find Every Page Is Page One topics that teach you just that skill.
Of course, your audience will include people with different levels of qualification. A tightly-coupled information set needs to know a lot about its audience, because it offers one principal route through the content which must be adapted to a particular audience level. But a loosely-coupled information set does not have this constraint. People with different levels of qualification will have different research strategies and will navigate through a content set differently using different topics to fill their personal information gaps.
This actually works best when each individual topic is written for the type of person who most commonly does the task it describes—when recipes are written for cooks. This allows for a natural progression and skill building without imposing a tightly coupled curriculum. This, in turn, preserves the ability to make changes in the content set with confidence at short notice.
A topic should stay on one level. Books often change levels, from the very general to the minutely detailed. A full documentation set will need topics on all of these levels, but each individual topic should stay on one level. It is up to the reader to decide when they need to change level in order to further their understanding. A recipe that requires sweating onions and merely mentions it in an instruction is on a different level from the topic that teaches you in detail how to sweat onions, but each stays on its own level.
An information set that plans when the reader will change levels is inherently tightly coupled. It is also making a decision for the reader that the reader would rather make for themselves. Staying on one level helps ensure the cohesion of individual topics. Loose coupling provides the means for reader to change levels when they please. Avoiding a mix of levels in individual topics ensures that the content is easy to change when changes occurs at a particular level of the system.
A topic should link richly. A loosely-coupled information set allows the reader to move in the direction of their own choosing. Cohesive topics make it possible for readers to come from anywhere and understand the topic. Links provide the loose coupling between topics that enables the reader to make that journey with ease. In an Agile environment it is important to have an effective link management strategy in place to ensure you can change content quickly without breaking links. However, ensuring that links express only a loose coupling between topics means that losing a link does not break the cohesion of a topic. High topic cohesion, therefore, makes managing links much easier.
By themselves, these principles describe how to make content useable for modern readers. That they also make it possible to create an Agile technical communication process is not an accident. Just as Agile software development is a response to the user's need for software that meets their changing needs quickly and effectively, Agile technical communication is about meeting rapidly changing information needs in a timely and efficient manner.
Scrum and standup meetings are simply a way of managing the design process that produces this kind of software and this kind of documentation. The real key to becoming an Agile technical communication organization is to change the way you design and architect content to support high cohesion and loose coupling through an Every Page is Page One information design.
Mark Baker is a 25-year veteran of the technical communication industry, with particular experience in developing task-oriented, topic-based content, and technical communication on the Web. He has worked as a technical writer, a publications manager, a structured authoring consultant and trainer, and as a designer, architect, and builder of structured authoring systems. He is currently president and principal consultant for Analecta Communications Inc. in Kitchener Waterloo, Canada.
References
Baker, Mark. 2013. Every Page Is Page One: Topic-based Writing for Technical Communication and the Web, XML Press.
Forrester Research, Software Innovation Requires A Loosley Coupled Applications Architecture, www.forrester.com/Brief+Software+Innovation+Requires+A+LooselyCoupled+Application+Architecture/fulltext/-/E-RES116565.
Goodliffe, Pete. 2014. Becoming a Better Programmer, O'Reilly.
Hurwitz, Judith. 2006. Service Oriented Architecture For Dummies, 2d ed. John Wiley & Sons, Inc.
Principles of Agile Development, http://agilemanifesto.org/principles.html.
Zakas, Nicholas C. 2012. Maintainable JavaScript, O'Reilly.
