By Tom Johnson | STC Senior Member
Agile software development seems to favor independent, autonomous teams. In contrast, enterprise content strategy and engineering practices look to harmonize content across multiple teams and boundaries. In a software development model where Agile dominates as the norm, how do you reconcile the larger need for enterprise content strategy?
Agile Versus the Enterprise
As our documentation teams at work have grown and fragmented, split and combined, often driven by the needs of Agile teams spun up around new projects, it’s caused me to think about how Agile fits in with enterprise content strategies. Agile teams tend to be independent, autonomous, smallish groups. They are single-threaded so they can be nimble and execute on a solution from end to end.
For example, companies might spin off a group of 20 people in various roles—engineers, testers, UX, project managers, and sometimes a technical writer—to build out a new solution for a long-shot project. Agile is a driving force that seems, at least in larger companies, to create startups within the enterprise. You need to move fast to stay competitive in a rapidly evolving tech landscape. Enterprises don’t move fast; startups do. You give the startup complete autonomy to deliver a solution, without any roadblocks.
Agile software engineering and product teams sensing extensive documentation needs tend to hire a dedicated technical writer specific to their team. These writers often arrive with only marginal obligations to adhere to wider enterprise concerns. In large enterprises, tech doc teams might be walled off from each other entirely by business lines, unaware of each other’s existence. Your Agile team (startup) might be the extent of your “company.”
If all writers have to plug into the same toolchain, taxonomy, style guide, reusable content source, approval process, and publishing workflows as every other writer in the enterprise, then you’ve slowed down the tech doc process and are at odds with the nimble and quick pace of Agile development. Given that most modern software development follows Scrum (a subset of Agile), tech writers plugging into this same methodology usually have to sacrifice ideals about enterprise content harmony to thrive in their Agile teams.
Enterprise Content Strategy and Engineering
In contrast to the independent, autonomous efforts of Agile teams, enterprise content strategy has much broader, more encompassing goals. Enterprise content strategists and content engineering teams might ask how the documentation produced by a single team fits within the larger enterprise context. This strategist would consider all the content touchpoints customers have across the enterprise through their product journey, from pre-sales touchpoints with marketing to touchpoints with solutions engineers and business development to post-sales touchpoints with technical documentation, support, troubleshooting, and more. What is the customer experience from end to end? How do you ensure consistency of terminology, style, and message across all of these enterprise lines?
Search is where enterprise content intersects—where customers see all content mixed together, often juxtaposed in jarring ways. Enterprise content strategy, by definition, forces you to cross department and team boundaries to coordinate on a higher level. For example, content engineers might strive for a unified taxonomy for all enterprise content so that it can feed into a larger faceted search or content management system where assets are described, shared, tracked, and re-used. Faceted search simply doesn’t work if all teams aren’t on board with the same terminology.
Given the compelling needs for coordination at an enterprise level, is Agile at odds with enterprise content strategy? If so, are the benefits of enterprise content strategy strong enough to overpower the driving forces of Agile? They seem incompatible. Let’s examine the cases for independent documentation and for unified content practices.
The Case for Independent Documentation
First, let’s consider the case for independent documentation, such as that produced by an Agile team that isn’t integrated and aligned within any larger, enterprise model. Any writer has to draw lines around their stewardship to survive, right? Take on too much, drawing the circles of ownership too large, and the work will crush you. You aren’t paid, most likely, to produce anything beyond the needs of your immediate business unit. The business lines of the organization define who you’re responsible to and what you’re responsible to produce.
Sure, you could scour all enterprise documentation and champion a case across all doc groups (perhaps across hundreds of technical writers in your organization, in many different business units, all reporting along separate business lines) to fall behind a common style guide, taxonomy, tool chain, and approach in documentation, but why? You’re paid to write documentation for a product from a particular business unit. Everything else is extracurricular. The additional effort to unify content across the enterprise will exhaust bandwidth you don’t have.
The Case for Unified Content Practices
Focusing your vision only on your Agile team’s needs, on the other hand, will likely lead to poor quality content. Content produced separately by many different teams, written in different styles, published by different tools and systems, without any larger awareness often results in a fragmented and disjointed content landscape.
Setting aside documentation concerns, engineers who build in isolation face similar problems. If engineers build separate systems that don’t integrate, the user experience also ends up being disjointed and frustrating. Users might find that one SDK doesn’t integrate with another, or that one tool is built on a technology that is incompatible with another.
At a previous company where I worked, customers were fed up with disparate systems that didn’t integrate with each other. When two major customers (who brought in millions in revenue) threatened not to renew, it caused shockwaves across the company. Business leaders halted the development of all new products as software teams undertook efforts to make the existing software work as a harmonizing suite of applications.
A hodgepodge of technology is understandable in mergers and acquisitions, but few users will be patient with the idea that the single company they interact with is actually made up of dozens of small, independent, internal “companies” and that each of these companies doesn’t seem to know what the others are working on or building, because none of the products work together. As a worse case, in massive companies, totally isolated teams might even be working on different solutions for the same problem, unaware of each other’s existence. Good documentation can’t be written with blinders on.
Harmony Is Hard
I wrote about the need to make information harmonize in the larger landscape in “Principle 3: Ensure information harmony in the larger landscape” (Johnson 2017) from my series on Simplifying Complexity. The basic principle is this:
Before adding new topics to an information landscape, look to see how the new information will fit in with the existing information—across all information forms, from docs to blogs, forums, white papers, and more. Synthesizing information to harmonize with the larger information landscape requires wide reading and analysis but is essential for the user experience, since users often bounce from one information source to another as they consume information.
Without question, it’s much harder to understand the larger landscape in which you’re writing and to assess how the content (the terms, styles, semantics, etc.) you’re using fits into other content which you likely do not own or over which you do not have stewardship. It’s easier to write a standalone article and push it out, like a blog post.
Strategies for Unifying Content
One strategy for unifying content involves bringing all tech writers into the same enterprise component content management system (CCMS) so they can see where content overlaps, re-use existing content in granular ways, find ways to leverage a common taxonomy, and more.
Although I often hear about the benefits of enterprise content in a CCMS, I’ve never seen it actually implemented in large companies. Centralizing content from the top down requires an engineering group to provide enterprise-wide tooling, yet each business unit is usually responsible for its own needs. One group’s needs don’t always align with another’s.
Even if some central governing body were to require all tech writers to use the same authoring and publishing tools, such an approach might stifle innovation. Writers would likely be stuck in the same systems for their entire corporate lives, with little ability to grow and evolve tools. Why not let these startups compete naturally with each other and see which one wins, drawing others to its side naturally rather than in a compulsory way?
Another strategy for allowing autonomous teams to harmonize within the larger content landscape is to create common glossaries and taxonomies. These can be created outside of any common tools. Much of the clarity and meaning in technical documentation is tied up with the terminology writers use. Control the use of terms at the source and you have a shot at making content (even if in different tools and systems) flow together more harmoniously.
This is easier than it sounds—content by nature is messy. Content on any documentation site might all read with the same general tone and follow similar structures (due to convention with industry standards), but in many places the content might be muddled and confusing. The content might use different terms to refer to the same process or have functionality that overlaps, or it might present solutions without adding the context of similar or contrasting solutions within the same space.
For example, during a recent project, I realized that the term “video skill” was used in different ways in the community and across other doc groups. My awareness of the term’s problematic meaning only surfaced as I started reading beyond my immediate group and user community. There wasn’t an easy solution to the problem, but at least I acknowledged this point of confusion in the documentation.
Independent documentation that does not consider anything beyond itself might be acceptable, just as a C or B- might be a passing grade on a test. If you want an “A” on your documentation, increasing its quality, you have to increase your sense of awareness (see Figure 1).
The first level of awareness is to master your own product. Understanding your product as a subject matter expert (SME) is practically required to write detailed documentation in the first place.
The next level is to be aware of documentation that other technical writers in other groups are working on. This is more applicable in larger companies with more than just a few tech writers. Good writers expand their horizons to understand docs they don’t necessarily own but that have some influence or relationship with their docs.
The next level is to be cognizant of content outside the documentation domain—content on blogs, white papers, ebooks, business development slide decks, and other collateral produced by groups outside of documentation. Groups like field engineering, business development, support, and so on are, in fact, producing content. Technical writers often aren’t aware of this content.
Stretching awareness even further, a good writer should also be aware of the competitor’s landscape. I wrote about this in “My Documentation Takeaways from the Boeing Disaster—Two Essential Doc Questions to Ask for Any Project” (Johnson 2019). In that post, I argued that good documentation should address the question, “How does this product differ from other products?” This question is rarely addressed in documentation since many companies do not call out competitors or compare their products with competitors.
This is one area where practitioners can learn from academic genre conventions. As a required section in academic articles, before diving into the details of one’s argument, nearly every academic article presents the context of previous research that has been done on the topic. Academics don’t just start writing without awareness of what has already been written on the topic. They start by surveying the landscape, summarizing what other research has been done, and then moving forward with their current argument. In documentation, this kind of landscape survey might involve mentioning how the product fits in the enterprise and competitive landscape of similar technologies.
Most writers won’t expand their horizons to consume more than their immediate product documentation requires. No one will force you to read documentation written by other departments or docs written by competitors. So should you even bother? Surely this expanded analysis isn’t scoped into your project plan or expectations, right? Where do you find the time or bandwidth to do it?
I’m not sure. Those who write our paychecks often won’t factor in time for this, especially given the time you already need to ramp up on the product’s technology itself (which is not insignificant in the developer documentation space).
Although I want to champion enterprise content strategy, if the Web has shown us the future, the future is probably independent publishing from disparate groups. It works out all right for the most part on the Internet, though enterprises might have another standard. For example, you won’t see articles in WebMD repurposing content from Yahoo Health covering the same topic. When you search for content, you get a lot of different hits on the same topic, with different approaches and styles and perspectives from different authors at different times on different websites. Content on the internet is redundant, outdated, disjointed, written in different styles for different purposes, audiences, business contexts, and more. But it works out all right—users find what they need, ignoring content that doesn’t quite match their search.
In the tension between Agile and the enterprise, most likely one embraces a middle ground here—finding some awareness of other content but not extensive awareness, reusing content within smaller groups in the same business units rather than across the enterprise. In general, good writers will read beyond their Agile team’s boundaries to provide better semantic context and fit with their content, but none of us has time to read endlessly and widely before the doc is due and another project takes the stage.
Whatever your position, if you want to write more informed documentation, try to climb up the pyramid of awareness. Start with awareness of content related to your product, and then as time permits, expand to learn about similar content across the company, then look at the same content in other business groups, and finally expand your analysis of competitor documentation for similar products. Most technical writers complete the base layer and maybe the second, but few climb up higher.
Johnson, Tom. “Principle 3: Ensure Information Harmony in the Larger Landscape.” I’d Rather Be Writing. 2017. https://idratherbewriting.com/simplifying-complexity/ensuring-information-harmony-in-the-larger-documentation-landscape.html.
Johnson, Tom. “My Documentation Takeaways from the Boeing Disaster—Two Essential Doc Questions to Ask for Any Project.” I’d Rather Be Writing. 20 March 2019. https://idratherbewriting.com/2019/03/20/two-doc-takeaways-from-boeing-disaster/.
TOM JOHNSON (firstname.lastname@example.org) is an STC member living in Sunnyvale, California. He works on developer documentation at Amazon and writes a blog on idratherbewriting.com.He also has an API documentation course available at idratherbewriting.com/learnapidoc.