One Documentation Lead that I spoke to last year managed to squeeze 23 tabs into a single, very colorful, spreadsheet. 23 tabs! Some of the rows in the tabs indicated that the content was approved, others were in various states of pending review. I never did figure out what happened to the rows that indicated that content had gone live without ever having gone through the process of being signed off. As I said, the Lead was extremely methodically managed – her problem was the system. The slow-motion collapse of the system that she managed was designed to process a certain volume of content, but had in fact been tasked to process far more.
Scale breaks things that used to work fine.
Scale breaks things that used to work fine
Scale breaks things that used to work fine. As a team grows it is no longer practical to manage a few writers and a shared folder with fast informal communications with other team members as needed. The informal workflow will fracture as the team and product lines scale.
As content becomes more complex and begins to require updates, simple editing of a document will no longer suffice. When multiple teams are authoring content for a single product, the risk that what readers are presented with to read and what they have written could differ greatly increases greatly. A safety notice could state something entirely different on a PDF as opposed to the same notice on a web page. A procedure could have been updated six months ago but only on 2 of 5 places where the procedure is published. In the worst case, such inconsistencies could be even illegal. In the best case, they are a cause for great embarrassment.
What do things look like for the technical writer when the team starts to scale the technical content? The number of writers on a team will likely increase. As the amount of new content required by a product increases, it will become necessary to have more than a few very good writers creating the content. Second, as a team scales, the processes that a team uses will become more formalized. These will include the various stages and check points along the way. These will typically be tracked in a spreadsheet. Third, and most important to the writer, the team will start to deal with the complexities of content created by others. This could be, for example, safety notices written by a safety specialist, and then approved by legal. This could also include procedures written by subject matter experts and then approved by a manager.
- They stop treating content as files and start treating it as structured data. This sounds abstract but it’s not. It means a warning is a warning everywhere, not a paragraph someone copied and slightly rephrased in a different document three product cycles ago.
- They build review into the process, not onto the end of it. Review-as-afterthought is where good content goes to get watered down or rubber-stamped past deadline.
- They get honest about where publishing breaks down. Usually it’s not the writing. It’s the handoff.
The collaboration problem nobody talks about enough
The biggest source of friction for the writing of technical content is the collaboration space between the writer and the subject matter experts (SMEs) and other stakeholders (e.g. product managers, legal, localization teams, etc.). Until the writer and all of the other stakeholders are on the same page, the quality of the technical content does not matter. And once all of the stakeholders are on the same page, the amount of time that it takes to complete the content does not matter. As long as everyone is working off of the same information, the content will complete just fine. However, until that point is reached, the entire team will be operating at the speed of the slowest reviewer. Typically, this person has all of the information required to complete the review.
Once you have laid out your workflow for creating technical content, the next challenge is going to be how you collaborate with other people to complete each of the tasks within that workflow. This, at first glance, seems to be a relatively straightforward matter. Writers work with Subject Matter Experts (SME’s) and Product Managers. All of them comment and revise as necessary. But in practice this is far from the case. Getting a safety notice approved can take weeks, especially when the only person who has any idea of how a particular subsystem works is on vacation.
Review is a process and should be planned out as such. To help manage the process, build in review checkpoints to the various stages of content. For example, a writer completes the first draft and then an SME reviews it. After that, the writer goes back to complete the second round of edits based on the SME’s comments. Then another review is held after the writer completes the first round of edits. Each of these review checkpoints can be viewed as if you were conducting an inspection on a building under construction. Are the walls straight? Is the roof leaking? Are the electrical and plumbing up to code? Are the firewalls between compartments sufficient? In documentation, these things translate to is the content accurate? Is it clear? Is it written in a proper and consistent fashion? Does it follow the appropriate style and standard for the organization. Each of these items can be checked at various points in the writing process, and can be completed before proceeding to the next stage of the process. In this way, the reviewer is not left with the massive task of reviewing an entire completed work.
(And, of course, there is the additional challenge of what it means for a piece of content to be approved. For example, in some organization, different people may have different perceptions as to who has final approval for certain content, or even believe that they have final approval for a piece of content and be unaware that others have the same perception but for different content. Addressing this kind of issue is a matter of organizational governance, not authoring tool functionality.
The part that actually requires discipline
As has already been pointed out, documentation isn’t something that you can do as a project and then celebrate because it’s been done. It needs to be a practice that is continued after the project has finished and attention has moved on to something else. And it needs to be continued in a deliberate and structured way, otherwise it will just degrade into nothing over time.
A structured process for creating and maintaining documentation does not become a sustainable practice overnight. In order for a structured workflow to be effective in producing high quality content, it must be actively maintained over time. The style guide which was so painstakingly developed and validated will become stale and less useful as time goes on. The review process which was worked out in such detail to ensure that documentation was written to the highest possible standards, will inevitably drift back to a less structured process. This will happen more quickly than most managers realize, and will certainly happen more quickly than most teams are prepared to handle.
So that’s scaling. How do you scale your authoring environment?
Efficient Authoring
The biggest problem with scaling technical writing is that most organizations try to solve the problem by hiring more writers. They feed more people into the broken process, with the result that more money is spent to write poor quality content faster.
The biggest value of a well-designed authoring environment is to improve authoring efficiency. Instead of throwing more people at the problem of scaling written information to reach more people, teams should invest in their existing writers by giving them better tools to work with. The biggest benefit of writing in componentized form is that it allows authors to write once and reuse the same content in many different places. This immediately reveals a lot of the duplicated effort that’s going on in trying to keep written work up to date and within certain bounds for consistency. There are a wide variety of tools now available for technical authors to use when creating technical content, and many of these have been designed specifically with large distributed teams in mind. A good starting point for anyone looking at new tools for their team would be to look at MadCap Create, a 100% cloud-based, 100% browser-based solution for creating, editing and managing technical content. It provides a huge number of advantages over more traditional solutions, and is especially well-suited to teams of distributed technical authors. And, as with all of MadCap’s solutions, it includes fully-featured support for structured authoring.
What to look for in any authoring setup:
- Single-source publishing so one update propagates everywhere it needs to go
- Real-time or asynchronous collaboration that doesn’t require emailing document versions back and forth
- Conditional content features for managing variations across products, audiences, or regions
- Audit trails, because “who changed this and when” becomes a very urgent question at the worst possible times
Publishing consistency: the finish line that keeps moving
You may very well create the very best technical content but it never gets published in the correct format, to the right audience at the right time. A printed manual has very different publishing guidelines than online help, printed documentation, software that contains documentation, or a set of in-app help tips. The team needs very clear guidelines for publishing.
| Output type | Common consistency risk | What helps |
| Web-based help | Stale content after product updates | Automated publishing triggers tied to releases |
| PDF manuals | Formatting drift across versions | Style templates locked at the template level |
| In-app content | Character limits ignored, tone mismatch | Content governance rules per channel |
| Localized content | Translation lag creating version gaps | Translation memory integration |
A bigger challenge for many teams, however, is getting the documentation published to the correct audiences. Even when all of the writing has been completed and put through a good review process, publication can be a real problem, especially because different formats (e.g. online help center vs. printed manual) and audiences require very different voices, just as different rule-governed behavior and varying amounts of detail. The set of rules for representing complex information within a very short in-app tooltip, for example, is far from obvious and in many ways is just as difficult to get right as formal written communication. This is “boring” stuff — a spreadsheet with 23 tabs, for example, to count up all of the tabs in all of the different formats, audiences, and channels — templates, style guides, etc. that support the many different formats, audiences, and channels for which one is writing.
So the way one views documentation is critical to scaling technical content. Documentation needs to be viewed as infrastructure or “boring” foundation to a company’s products and services rather than as another deliverable to be produced by a team of writers. This is what I mean by the third major change needed to scale technical content, the change in the way that teams view and manage documentation. It is very easy to create a huge spreadsheet with 23 tabs to manage all of the different components of a company’s documentation and to refer to that spreadsheet as the “documentation management system” for a company. The problem
