This picture of a technical writer spending 40 minutes trying to figure out which “final” version of a user guide was actually the “real” one was posted by a colleague on a discussion list this afternoon.
That story isn’t funny. It’s Tuesday.
People Problem, Masquerading as a Tooling Problem.
Most teams treat content chaos as a tooling problem but it is actually a coordination problem of coordination that is being made worse by the tooling that the team is using to try to manage the chaos. Thus, the root of the problem is the problem of the team working together as a team, and the tooling is just a major exacerbation of that problem.
But, for the documentation and content operations teams the content is very interdependent. So changing a product name in one place can have very far-reaching effects. For example, changing a product name in one place can affect 20 procedures, 6 tooltips, 3 PDFs and 1 training module in 18 locations throughout the entire documentation set. So, trying to manage this all manually can be like trying to untangle a large number of headphone cables in the dark. Yes, it is technically possible, but in practice it would burn up a lot of time and would probably miss some important changes along the way.
What actually changes when work moves to the cloud
Some practical differences show up immediately:
- A subject matter expert in a different time zone can review a draft without you having to export, email, wait, re-import, and reconcile two versions of the same file
- Your single-source content stays single-source, even when multiple writers are touching it simultaneously
- Publishing to multiple outputs (web help, PDF, mobile) doesn’t require a separate manual step for each one
- Audit trails exist by default, which matters more than people realize until there’s a compliance question
One note worth mentioning is that by “cloud” we’re referring to many different things. For us, as documentation teams, it really doesn’t matter where the storage part is living. What matters is that the content, the writers, the reviewers, and the publishing of that content are all living in the same environment. They’re all connected through the same infrastructure. That our team doesn’t have to manage around the same infrastructure that we’re using to do our work every day, that the infrastructure just works for us is what’s really important.
Later, one realizes that the biggest gain in confidence is not the hours one saves, but rather the fact that a writer has confidence in the work he or she is doing, a reviewer can be sure that his or her feedback has been incorporated, and a manager can easily find out the status of all writers on a team.
Example Scenario: Onboarding New Technical Writer
For new writers on a team using desktops plus a shared drive for their content and documentation the typical process for getting a writer up to speed on all the documentation for a product would be as follows:
- Install the authoring tool on their machine
- Configure it (which takes longer than anyone admits in planning meetings)
- Get them access to the right folders, which involves at least two IT tickets
- Walk them through which folder is current, which is archived, and which is “don’t touch that one”
- Hope they remember all of this two weeks later when you’re not available to ask
Of course, all this can be set up in a matter of minutes, for a writer who works with documentation stored in the cloud. The writer simply accesses the documentation and can immediately see the structure of the content, which is part of his or her work environment.
It’s not right for every team
The previous sections painted a rosy view of how to use cloud-based documentation tools. In truth, there are situations where local tools are better. This could be for a variety of reasons: because of data residency requirements, because you work in an air-gapped environment (e.g. finance, government), or because you work with a lot of very stable content (e.g. API documentation). For each of these situations, the trade-offs made by using local documentation tools as opposed to cloud-based content management tools would likely need to be greater than the sum of the trade-offs for using the cloud-based tools as opposed to local documentation tools.
A local content vs. cloud content comparison.
| Scenario | Local/desktop setup | Cloud-based setup |
| Distributed team across time zones | Painful; lots of version juggling | Works naturally; real-time access |
| Frequent SME review cycles | Email attachments, reconciliation headaches | In-platform review, tracked changes |
| Single writer, stable content | Perfectly fine | Useful but not urgent |
| Multiple output formats required | Manual steps, error-prone | Centralized publishing pipeline |
| Strict data residency needs | Easier to control | Depends on vendor; needs vetting |
(Addition to previous table for single writer/stable content): Many teams write locally because it seems to work. A single writer writes a single piece of content and that is it for a while. But, in many organizations, documentation of products becomes a compliance issue. At some point, an audit will be performed and the locally managed content will add more overhead than value. This is a common scenario that I find to be all too familiar.
The question worth sitting with
How much time are you spending in content logistics (as opposed to creating content)? That is, how much time do you spend: looking for files, working out what other people wrote, reconciling changes, re-publishing a small change, etc. Because this can quietly and relentlessly be consuming a lot of your time. I would really like to know what the true cost of this is for your team.
It is an interesting question to ask how much time you and your team are currently wasting to manage the content chaos of your documentation. The time spent to manage a shared folder, to keep track of updated documentation, to merge changed documentation, to republish a small change, to answer the question which version of the documentation is current. All this time is completely wasted and could be better used to create new content or to improve the existing content.
Four copies of a user guide – three on shared drives – created a bit of a problem. For a number of months, no one knew which was the current version. After finally spending 40 minutes of his time, to find out, it became clear to this writer that such a situation created a significant drain on the time of writers and other support staff. That time could be better spent creating additional, high quality documentation for customers. And, after all, is not the goal of documentation to support the customer in getting the best out of a product? The last thing anyone wants is to create a bit of a farce by including the wrong product name in the documentation for a product’s shipment. So, where is the best place to start looking for a solution to this type of problem?
Why Teams Are Switching to Cloud Based Documentation Tools. Most teams switch to cloud based documentation tools for one simple reason. The costs of documenting with the current solution have become too high.
