Bringing Xandr Documentation into the Future
Historically, excellent technical documentation combines art and science, not just to collect information, but to create understanding using words. Readers should experience information transfer as smooth, transparent, and simple. As a writer and editor on Xandr’s Technical Communication team, though, I often find myself communicating about the invisible complexity of documentation. Creating a pleasant user experience for an application requires intense collaboration and a big range of expertises; similarly, creating easy-to-use technical information requires solving hard problems behind the scenes. Solving those problems includes making sure our information processes can move forward along with our product technology.
Technical writing is more than writing
If you’re not a technical writer, you’re likely to be most familiar either with API documentation (if you’re a software developer), or with consumer documentation targeted to a very specific need. At Xandr, our product offerings are both broad and complex. Our documentation not only has to cover the ins and outs of an intricate, highly flexible user interface: it also supports integrations with third-party tools, the complexity of advertising optimization, and the deep technical information that helps developers build their own apps on top of our platform. That’s a huge amount of information, and it evolves rapidly. In other words, documenting our products requires an approach that can handle documentation at scale and over time.
Let’s unpack what scaling and maintenance mean for documentation.
When you write a letter, blog post, or email, you probably aren’t expecting any of the following to happen in the future:
- People will keep referring to what you wrote for years to come. They’ll get very annoyed if the facts are out of date.
- There is so much information out there that your material gets lost. Even people who are highly motivated to read what you wrote will not be able to find it — even with on-site search.
- Other writers will take what you wrote and add some sections, but the new bits will be in a different writing style.
- Other writers are writing related documents all the time, but they’re formatted in a totally different way, or they use different terminology, so nothing matches and everything looks slipshod.
- Several different publications will use parts of your writing, but in different combinations and organizations. Alternately, three different versions of what you wrote will exist at the same time and in the same publication, but 10% of the content will be slightly different. When the facts change, these versions may get out of sync.
- The platform or medium in which you wrote it will be discontinued, so if you want to keep publishing it on your website, you’ll have to master a whole new set of technical processes to keep it out there. (OK, this happens sometimes with blogs, but at a lesser scale.)
- Other people will need to use the same files you do to get writing done, but they’ll be making different (possibly conflicting) updates with different deadlines. Just as with code, merging and branching sometimes get complex.
With many hundreds of documents in play, covering an overlapping series of products that evolve rapidly and require deep technical understanding, our documentation team has to solve all these problems to avoid creating a frustrating customer experience. We not only need to produce timely, accurate documentation for the many new features Xandr releases, but also maintain our existing documentation base by removing information that’s no longer accurate.
We also constantly need to identify gaps that challenge our customers, in order to make sure they can do their jobs. Finally, we need to make sure our docs are usable — searchable, well organized, and well presented. It’s a big challenge with many moving parts.
In the last couple of years, the story of Xandr documentation has been one of almost constant change and growth, as we weaned ourselves off processes and tools that limited our ability to adapt to changing conditions. As the Xandr product universe has grown and diversified, our team has transformed operations to handle information at scale, while staying ahead of Xandr’s technological evolution.
Some details
As Xandr grew and diversified its product portfolio, Xandr’s docs team upped our game in the following areas:
- Source: the format and technology we use to create docs
- Publication: how we get documentation reviewed and published
- User Experience: how customers find and interact with information in our documentation portal
- Case deflection: how we find and address customer gaps to create a more satisfying information experience and reduce Support involvement
Making our documentation source “smarter”
A couple of years ago we made the big leap from authoring content in Markdown to coding it in DITA XML, a flavor of XML with custom markup designed for technical communication. (DITA stands for Darwin Information Typing Architecture and is an open-source standard: read more here if you’re curious.) This change represented a whole new way of writing for much of our team. It might seem counterintuitive to write words in code, but DITA’s modularity and semantic markup offer great flexibility in enabling multiple outputs. For example, a website, a context-sensitive Help app, and a chatbot could all use the same files, but look and function very differently.
Xandr used to operate as a single product: now it’s a DSP, an SSP, and a curation app, plus a whole family of products that handle TV advertising. DITA lets us handle the overlaps between multiple products using complex conditionalization. That means we don’t have to maintain separate files for every product that uses some of the same information — resulting in thousands of hours of duplicate effort saved, not to mention far greater accuracy than we’d be able to achieve without the ability to reuse existing documents.
Finally, DITA is “portable.” That means if our current toolset is discontinued, we can bring the code into a new system without having to convert it to a new file format, or reapply all the formatting we’ve painstakingly added.
Streamlining review and publication
Along with DITA, we’ve adopted a content management system (CMS) to help us manage branching and versioning. Our CMS also provides a web-based review system to collaborate with subject matter experts without emailing multiple versions of files around. We can branch, review, and build in the same interface. And we can run reports identifying content that’s stale, so we can update it or remove it.
Publishing documentation at Xandr used to require a labor-intensive build process involving command lines and multiple apps and libraries installed on a writer’s computer. We also had no way to stand up a staging server to verify changes before they went live on our documentation website. Our current processes allow us to view our changes in staging and push corrections and updates rapidly to both the website and the in-product Help — no more waiting for a weekly build to get it right.
Building out the documentation portal
For the last two years, we’ve been working with Zoomin Software to create and refine a unified documentation portal. Our API docs, product docs, and knowledge base articles now use a single searchable and filterable website, which lets customers quickly find articles with the answers they need. They can even favorite the docs they like and provide feedback right in the portal.
Deflecting support cases
Our documentation used to be hidden behind a login: most of it is now public, and that means we have two sets of analytics to work with: Zoomin’s and Google’s. With enhanced access to statistics about web searches, on-site searches, and searches within our in-app Help, we’re getting new insights about what our customers are looking for. These insights help us identify where to allocate effort, understand the terminology our customers are using, and even identify content that’s not getting used much, so we can decide if it’s still valuable. We’ve also launched a project to target those areas where customers struggle by creating highly specific, task-based articles to supplement our existing information.
Most excitingly, we’ve partnered with the Xandr Support team to roll out an integration with Salesforce that directly interfaces with our Support site. We can now proactively offer relevant documentation to customers filing a case — when just-in-time information can solve their problems, they can move on to success without ever creating a case.
Futureworld
Some documentation practices don’t change. From Leonardo da Vinci’s sketches of flying machines on up through the interactive chatbot, solid documentation will always be based on technological learning and clear communication of how things work. How that gets done, though, is highly subject to change. As our products and the state of documentation tools and workflows evolve, we’ll continue to look for both high- and low-tech opportunities to provide information that’s relevant, useful, and up to date.
