I was talking to my colleague a few days ago, and she spent 2 days searching for the right manual for one of the products we support. Writing and publishing that in 2 days time could have been so much better for her and for us as a team if only she could have found the right manual in 2 days time instead of 6 months out of date. The manual she found was labeled as the “current” version, but was in a folder somewhere that required a bit of an archeological dig to find.
That story isn’t unusual. It’s practically a genre.
Technical writing isn’t just creating content – it’s the delivery of that content to the people who need it. That delivery can be as simple as a document sitting in a folder on a network, or as complex as a multi-step process involving multiple systems. The worst case is when the process of finding the content to begin with is so convoluted that it has to be done through a support ticket. If finding a 30 second document to read takes a support staff member that long to file a ticket, there is a problem with the delivery of that content.
What a content delivery platform actually does
If documentation teams are getting frustrated with authoring tools not meeting promises, that’s a whole different article for now, but for now, let’s focus on the important stuff – the content delivery platform. After a short review of what a content delivery platform does, I’ll detail out the many benefits that documenting can receive from using the right content delivery platform.
The baking is not the problem. Delivering that bread to the consumer is the problem. Just as you wouldn’t build a distribution network in your bakery, you shouldn’t confuse your authoring tool with your content delivery platform. The bakery is where you write your documentation, the distribution network is where you deliver that documentation to end users.
A proper content delivery platform handles things like:
- Serving the correct content version based on user role, product, or region
- Syncing updates instantly across multiple output channels, so you’re not manually pushing changes to eight different portals
- Controlling access so internal teams see one thing and external customers see another
- Tracking how users actually interact with content, which pages they exit from, where they get stuck
Go through the process outlined above step by step and identify where users give up. Such a gap in the documentation process is an admission that there is a gap in the content that has been written for the process and that rewording step 3 above will not fix it.
The access problem is messier than it looks
This kind of problem is generally not announced to everyone. It is not like the system is saying “Oh, no, you can’t find that. Go ask support!” Rather, the problem is slowly accumulating over time. Users search for terms that seem relevant, but are not returned because the content was published in a different system under a different name. And then the users just go away. They send an email to support, but more likely they just give up. It is frustrating for the users, and for support, but it is not immediately obvious as a problem to be solved.
I was speaking with a documentation lead last year who managed to put his documentation on four portals of content, none of which shared a search index. So users would have to know which portal a particular piece of documentation was on before they could even search for it. It’s like being given a library card and then being told that the books are all organized by the color of their spines. So technically he could have organized his content that way and it would have been “navigable”. But it would have been completely impractical.
The problem that can be caused by multiple sites and portals within an organization to deliver content to is something that can be easily solved with a purpose-built delivery platform. Here at MadCap Software, we have created the MadCap Syndicate content delivery platform which allows you to deliver content to all of the various sites and portals within your organization as if they were a single entity. The delivery platform can manage your content’s versioning across product lines, and allow your users to search for information as if it all existed within a single giant library, without ever having to know or care where a particular piece of content actually resides.
The best delivery of information feels like nothing, it is invisible. And the hardest thing to build is invisible infrastructure.
Setting up the right delivery platform makes all the difference
| Without a delivery platform | With a delivery platform |
| Manual updates pushed to each channel separately | Single-source publishing syncs updates automatically |
| Users search across disconnected systems | Unified search across all content, regardless of source |
| Everyone sees the same content, regardless of role | Access filtered by user type, product version, or region |
| No visibility into how content is being used | Analytics show real user behavior and drop-off points |
Versioning is where things get genuinely complicated
Search and Relevance problems affect users in two ways. As we discussed above the search problems are harder to surface than the relevance problems but they are just as bad for users. And the biggest relevance problem of all is versioning.
As companies have releases of products in the market, managing the version of content (e.g. documentation, release notes) can be a significant challenge. The worst experience for users is to go through a process of steps and find that the last step does not work. Typically this is because the documentation was written for a different version of the product than what the user is running. In a very real sense, this problem is one of relevance. Delivery systems manage the version of content so that the correct content is delivered to the user for their specific context. The context can be as simple as a login ID, or as complex as embedded metadata in a URL.
For example, content can be marked up with information regarding the product version for which it was written. The delivery system can then ensure that users with a different version of the product are only delivered the most relevant content. That information can come from a user’s login, from the URL of the content itself, and from the metadata embedded within the content. This information can even come from a search results list (where the information delivered to the user as part of having search results in the first place is the relevance of the access information).
What do teams actually get out of better documentation and content delivery?
What documentation and content operations teams gain from good documentation delivery is time – time to do something more interesting than mind-numbing work. Work that is tedious, dull and boring. The kind of work that, when done enough times, can start to wear down even the most patient of individuals. Hours spent by documentation leads, managers and teams working with documentation, chasing after various portal versions, trying to figure out why certain content is not available to users, tracking down individual users to find out why they cannot find what they need, reconciling updates to content that for some reason or other did not make it into the appropriate portal.
When the delivery of documentation is working properly, you will be doing better work, work that requires thought and that is why you are in this job in the first place.
- Audit your current content channels and identify where users experience access friction
- Map which user groups need different content experiences (role, region, product version)
- Evaluate whether your authoring output format is compatible with centralized delivery
- Pilot a delivery platform with one product line before rolling out broadly
Access to user documentation is not a User Experience problem that has been re-branded as a documentation problem. It is a systems problem and, as with all systems problems, the root cause of the problem can only be addressed by better systems, not by people already exhausted from fighting against suboptimal systems to do their work getting asked to do more of the same.
