I spent the Thanksgiving holiday visiting relatives in San Diego. We visited Balboa Park, the site of two international expositions (in 1915 and 1935). The buildings for these expositions, although elaborately detailed, were built from chicken wire and plaster. They were intended to last through the exposition year and then they would be torn down. They’re beautiful, but they were never meant to last. They’ve both been named to the national register of historic landmarks.
Which sounds a lot like our documentation (except for the historic landmarks part).
We create documentation (and graphics and videos) in the face of two concurrent timelines: the product that we’re documenting, and the person who needs help. These are short timelines–products are ephemeral, and our customers are impatient.
Like the structures built for the exhibitions 100 years ago, we often build our documentation as quickly as possible, with the intention to make it last until the next product release, knowing that it will need serious structural repairs. Patching the docs is like applying some plaster to fix cracks in the building: it will hold for a while, but you know that eventually you’ll need to do some major remodeling.
Much as we’d like to think otherwise, we’re not building an exhibition park to showcase the wonders of the age. Our documentation does show our customers how they can get the most value out of our products. We might be writing for hundreds of customers or only a handful, but our documentation needs to be as functional and structurally sound as possible to handle whatever capacity might be required.
When authorities decided that they wanted some of the buildings in Balboa Park to last longer than a year, they had to figure out how to make them structurally sound. As a result, they had to rebuild them, tearing down the plaster and replacing it with concrete.
Some technical writers have the time to plan and build structurally sound documentation based on a well thought-out information architecture. When the product is updated, those writers can focus on cleaning up the façade and patching a few cracks, as well as adding a new building or two.
For those of us working in agile, fast-moving development environments, our constant time constraints often force us to take the chicken-wire-and-plaster route. We build something that serves our customers right now, and leave the long-term planning for tomorrow.
With that, we can meet two of the requirements of the “iron triangle”: fast and cheap. And it might even be good…enough. Just as long as the customers don’t lean on it too much.
But let’s look at it from our customers’ point of view.
Unlike the exhibition buildings, product documentation rarely inspires awe and wonder in our guests. No one plans to spend a day with documentation, wandering around the topics and marveling at what we’ve built. Our customers aren’t sightseeing, and our job is to help them help themselves as quickly as possible.
That’s the point of our user assistance documentation: give the customer an answer as quickly as possible without making them wander. But great user experience doesn’t mean we shouldn’t encourage a bit of wandering. There’s a big difference between “desperately searching for help” and “choosing the road less traveled.” Documentation (in all its forms and formats) should balance just-in-time support with optimizing user experience.
We should give them the opportunity to wander, to learn more about our products by reading about the hows and whys and WIIFMs. Don’t lead them by the nose, but add signposts, guides, and “You are here” markers.
We can address the balance of too little/too much by enticing our customers to explore the product via the documentation. Much more than the old standby “See Also” sections, we can direct our readers towards complimentary topics. We can create interesting, even entertaining scenarios that show them what to do next, how they can expand their usage of the product, or background information that we can’t cover in our traditional documentation.
For example, I’m documenting how to use my company’s product to perform customer retention analysis. I can document the basic concepts, the workflow, best practices, and include an example or two, but there’s still more to learn about the product and how it does what it does. Fortunately, our marketing team has created a whitepaper and video about this topic. It’s not often that we have related content immediately available, but is an excellent example of how we can work with other departments to cross-sell our content.
We usually think of marketing content as pre-sales material, designed to pique a potential customer’s interest and bring them into the sales process. But whitepapers and videos are a great way to introduce new features to customers and get them to think about how they can use our products in new ways. And it’s worth remembering that today’s buyers look for technical content long before they make contact with a sales person.
Our customers aren’t looking for pointless ornamentation (and we don’t have time to create that!). But in addition to pointing them to supplementary information, we can make our docs more appealing by adding illustrations, videos, and screenshots. While these types of content require the most frequent updates (depending on how quickly your product changes), they’re also much more than decorative flourishes on the overall architecture. Providing content in multiple formats only breaks up the “walls of text” that can intimidate your customers, especially new customers. But by providing videos and illustrations within the context the user wants or needs, you can expand your help content to be more fully immersive customer experience. That tends to create life-long customers who don’t need rebuilding once a year.
All of this works to present appealing, user-friendly product help, but it’s much more structural than superficial. If we plan to continuously reshape our documentation (and even tear down the particularly unstable parts), we can think about building new structures to serve our customers.
