Tech Writers Must Learn to Stage Content Better

By | 2014/07/07

Some technical writers are proud of the utilitarian nature of their content. This isn’t marketing, they will say, with no attempt to veil their contempt for anything that might please or persuade. The customer has already bought the product, they will explain, so there is nothing left to sell.

This is wrong on a number of counts.

Documentation has to sell

There is a lot left to sell after the user makes an initial purchase. There are more copies to sell across the user’s organization. There is the next version to sell. There are other products your company wants to sell. There are the people that each current customer influences that your company want’s to sell to. But even more basic than this, your content has to be sold to the user. True, you are not asking the user for cash; just for time and trust. But time and trust are currency, and if we cannot command the reader’s time and trust, how can we expect to command our salaries?

Content and the customer relationship

The truth is, there is almost everything left to sell when the user approaches your content. They will need your content most at the earliest stage of their relationship with your company, at the time when their investment is minimal and moving away is easiest, both psychologically and financially. It is the time when cementing a long term relationship with the newly acquired customer is critical. It is the time to sell the idea that yours is a company that is worth establishing a long term relationship with, and your content can and should be a critical component of that.

The customer relationship and the value of tech comm

If the executives in your company don’t value technical communication the way you think they should, it is because it does not help sell this relationship. And if it does not help sell this relationship, it is because we have paid so little attention to making it sell, and because we have been so openly hostile to the very idea that it should sell, that it should have anything to do with selling.

Now you may argue that technical documentation contributes to customer retention by making accurate information available to customers. Sorry, but that is not nearly enough. Customers are not buying the idea of reading the documentation, and if they are not buying, we need to do more to make it sell. If we want to sell it, we need to stage it for sale.

Staging tech comm for sale

Larry Kunz recent blog post, Granite countertops and stainless steel appliances, asks if our content needs the equivalent of the granite and stainless steel of modern kitchens, or if more utilitarian presentation is sufficient and appropriate for technical communication. This metaphor got me thinking about staging — the art of preparing a house for sale — and got me asking if we are doing the right things to stage our content to appeal to the user.

Staging your content for sale is not about fixing the typos and picking the right font. That stuff is often important (though not necessarily always) but it is not staging. Keeping your house neat and clean while you are selling it is important, but it is not staging. Staging involves (from my recent experience) a massive decluttering, the probable removal of half your furniture and possessions (including all but a handful of your books!), repainting in neutral colors, the purchase and installation of draperies and bedspreads, new towels, and the organization of your furniture to give the impression of order, simplicity, and space, even at the expense of any degree of utility or comfort. A staged house is hard to live in, but it sells the idea that you would want to live in it.

Staging products and content

Bruce Tognazzini talks about the buyer as “The Third User” and shows how Apple designs its interfaces to appeal to the buyer in the store, even at the expense of features that would make the interface more usable in everyday use. Just as staging a house makes it hard to live in, but creates a sense of simplicity, order, and space, Apple’s interfaces are staged to create the impression of simplicity and usability, even at the expense of leaving out features that would make them more usable.

It seems to be working for them. 

In 5 Useless Elements You Need To Remove From Your Blog Right Now!, Adam Connell describes the impact that decluttering can have on how often people visit your blog and how likely they are to do follow-on actions like sign up for your newsletter. The elements he describes are not really useless — you can think of potential uses for all of them. But they contribute to poor staging of your blog, which detracts from the essentials of increasing visits and generating sign-ups. (Expect some changes in the layout of this blog soon. It needs to be staged better.)

The impression of usability trumps usability

It is not hard to see why the impression of usability trumps actual usability. Practice and familiarity can compensate for all kinds of usability flaws, but usability is moot unless there is actual use. The first challenge is to get the user to use. It’s why drug dealers give out free samples until you are hooked. It’s why the freemium model works. It does not matter how usable something is in principle if it is so off-putting in appearance that no one tries to use it.

Tri-pane help and the staging of content

The design of tri-pane help rubs the reader's nose in the complexity of the documentation set -- which implies a similar complexity in the product.

The design of tri-pane help rubs the reader’s nose in the complexity of the documentation set — which implies a similar complexity in the product.

Here’s the problem for tech comm: the classic tri-pane help system is not well-staged content. From the first touch, it screams “Look how big and complicated I am. Look at how many pages there are. Look at how deep they are nested. Look at all these controls you will have to use to navigate me. Tri-pane help is to staging content what pulling all your stuff out of your closets and piling it in the front hallway is to staging your house.

Help systems may be full of utility — or at least, full of utilities, multiple ways to view and navigate the content, multiple buttons to push to move around it in different ways. But they are lousy staging. They are like a house with all the wires and the plumbing exposed, and no doors on the bathrooms. They scream discomfort and confusion.

The much-maligned PDF is a far less usable vehicle for tech comm than a well-organized online help system, but it is actually better staged. It presents a single pane and a search box. Love them or hate them, everyone knows how to use a PDF. Videos stage even better. While they have their applications, videos are lousy for many tech comm tasks — tedious, impossible to navigate, impossible to search, impossible to use for reference, etc. — but they stage brilliantly. Their entire interface is a single triangular button facing left. No wonder users ask for videos and PDFs even when they are not appropriate or usable for the subject they are interested in: they are staged so much better than the content that would actually help them.

The cost of poorly staged content

The bulk of practical tech comm is and will almost certainly remain topic-oriented and text based. This is the only format that provides the navigation, random access, searchability, and reference capability that users need. But we are staging it really badly. This is bad for our customers, who are reluctant to buy what we are selling. And it is directly damaging to us as a profession. It hurts our reputation and the reputation of our work. Other people in our organization don’t think what we do adds value — because we don’t stage our work well enough for them to see the value, or for our customers to realize the value.

As a profession, we need to learn to stage our content successfully.

Staging complex content

There are difficulties here, of course. Some of the things we document are complicated. Really complicated. But that does not mean that our content has to look complicated. In fact, it is the very reason that the help should not look complicated. Asserting the complexity of the product through the help only serves to discourage the users from trying and learning. It increases the likelihood of their abandoning their task, and in doing so robs them of the success that would encourage and the experience that would teach. This increases the likelihood that they will abandon the product rather than mastering it or that they will abandon our documentation in favor of other sources of information.

Even if a product is complicated overall, that does not mean that every individual task, feature, or concept is complicated. Throwing all the content in the user’s face when they look for help with something simple is distracting them from the simplicity of the immediate task, feature, or concept by asserting the complexity of the whole. Staging content is all about making the individual task, feature, or concept seem inviting to learn or try.

Bottom-up architectures and the staging of content

In the paper world, staging content was difficult. There was no hiding the physical bulk of a paper document, the complexity of its TOC, or the length of its index. Minimalism offered a prescription for improved staging, but at the cost of the loss of comprehensive information. Fortunately, online media don’t have the same constraints. We can create documentation that looks simple in whatever face it turns to the reader, while remaining thorough and comprehensive in the depth of its coverage. Thanks to hypertext linking, we are not restricted to offering the reader the navigation of the whole via a TOC or index — we can offer locally relevant links on every page that can allow the reader to move effectively through the content without ever being aware of how extensive it is, or the overall complexity of the product it describes. Bottom-up information architectures can stage even the largest content sets effectively. We can be well staged, comprehensive, and usable all at the same time, if we put our minds to it.

Some concrete thoughts on how to stage content in future posts. In the meantime, please share your ideas in the comments.

Category: Content Strategy Technical Communication

About Mark Baker

I am an aspiring novelist and former technical writer and content strategist. On the technical side, I am the author of Every Page is Page One: Topic-based Writing for Technical Communication and the Web and Structured Writing: Rhetoric and Process. I blog at and tweet as @mbakeranalecta.

15 thoughts on “Tech Writers Must Learn to Stage Content Better

  1. Vinish Garg

    What an absolutely delightful post. You nailed it so well when you say “A staged house is hard to live in, but it sells the idea that you would want to live in it.” How successfully we execute it depends on so many variables, well-known to us.

    While planning the inventory for my current CRM documentation task, I struggled to plan for re-usable content chunks. This is because the platform entities are so contextually co-related that it is difficult to sell the platform when following minimalism approach. I see that the content chunks repeat, I see some clutter that I am so tempted to trash but then I lose the ‘selling’ value if I stage the content well enough.

    However, this post gives some real good food for thought on how we can brand content while following minimalism. Thank you for causing the stir!

    1. Mark Baker Post author

      Thanks for the comment, Vinish.

      I think one of the things that we need to remember is that while a house is sold all at once, most technology products are sold a bit at a time. That is, not only is it common today for customers to start with small purchases and slowly build up — through trial projects or purchase models such as freemium, free software + paid services, and software subscriptions, the total economic benefit that the company receives from a customer engagement continues and builds over the long term through maintenance revenues, follow on sales, and word of mouth advertizing.

      This means that the user does not have to learn the whole of a system at first encounter. In fact, most systems have far more functionality than any user needs, and in many cases the users is delighted most by having a system that is simple to use up front, but turns out to have the capability to do more as business needs change.

      When we come to the realization that docs have to sell, we may fall into the same trap of many inexperience sales people of wanting to tell the prospect everything at once. Showing all the complexity up front can scare off the user who is not prepared to do that much mental work. But the documentation still has to treat all the functionality so that it can do the ongoing sales work that needs to be done.

      Staging is an approach to selling that emphasises less rather than more — removing the clutter that prevents the user from seeing the solution they are seeking plain and clear. At the same time, because a user’s engagement with the product grows over time, the docs have to keep on selling as the user discovers new needs to be met.

      This is why I think a bottom-up architecture is the ideal way to stage technical content. It allows for a richness and depth in the overall documentation set while keeping things clean and simple at each individual touch point. Thus the content can always be well staged for the next step of the ongoing sales process.

      1. Vinish Garg

        I got it now.

        One way to stage content is to use the progress disclosure of information’ approach that you had discussed in another post a while back.

        1. Mark Baker Post author

          Yes, I agree that progressive disclosure can work in some cases. In the broad sense, staging complex content is all about progressive disclosure — not exposing readers to the full extent of the content, but allowing them to find what they need when they need it.

          I’m not a fan of the conventional open/close implementation of progressive disclosure, however. It is an additional piece of display semantics that the user has to understand and operate, which is bad for staging. Open/close style progressive disclosure breaks the back button — you click to display new content, but if you then want to go back to the previous view, clicking the back button won’t work — it will take you one step further back than you intended. I find Google’s image search endlessly frustrating because of this.

          In most cases, progressive disclosure through simple linking can do the same job. It is more flexible, because it is non-linear, and it demands less of the user because it relies solely on basic Web controls: links and the back button. In fact, all uses of hypertext linking are a form of progressive disclosure. I don’t really think we need an alternate mechanism to accomplish the same thing.

  2. Kalpana Thakar

    I agree with you Mark. We do need to learn the art of staging content else, at times, even the product suffers- I have known of instances where the customers have bought a particular product only on account of better documentation (in this case better was in terms of the way the content was staged which helped the customer easily navigate to the required information as and when they needed it.). Unfortunately, lack of time and resources, complying to company documentation standards, etc., take us away from staging content the right way.

    1. Mark Baker Post author

      Thanks for the comment, Kalpana.

      Indeed, established company documentation standards often get in the way of staging content well, either because they were developed in the age of paper, or they were developed with no thought to staging. We have to work to change those standards if we want to stay relevant. History is full of products and professions that marched to extinction clutching fast to their established standards all the way.

  3. Alex Knappe

    Actually, staging hasn’t got so much do to with the amount of information. It is about a clear line, design and eye-candy.
    The same information put into a standard Word layout or a pretty Indesign layout already makes a difference. One usually can tell at the first glimpse, if some document has been done in either of the tools.
    Next stop is Typography. Arial – while being a good choice unicode wise – is a poor choice when it comes down to style or eye-comfort.
    The size of fonts and the whole gray impression of a page add also to comfort and the will to read.
    Pictures and graphics also play a mayor role – to few of them and the reader won’t stay long with the topic. Too much of them and the reader is too distracted.
    Too much or too few content in them also creates distrust.
    2D only when necessary, 3D when possible. Detail or overview?!
    Color is a must, if you want to keep a user reading. Better sparse than offensive, leaving enough white space.
    This is all adding to a “polished” impression, nice and tidy – just as those showrooms in warehouse catalogues.
    I’m daring to say, that this is much more important, than correct grammar or spelling (not that those are unimportant) and even covers some lack of information.
    As long as the reader is pleased by his reading environment, he is much more forgiving in regards of navigation, content and correctness.
    This works pretty much for every piece of marketing information – so why shouldn’t it work for documentation too.

    Maybe it’s just some psychological trickery, but if something looks valuable, people trust in it, that it actually IS valuable. People react completely different to the same person wearing either a suit or rags, despite the same character is behind it. That’s a fact and can directly be transferred to the world of things (and therefore to documentation).
    I worked long enough for a company, that sold chinese eletronics garbage to people and called the stuff “premium” goods. Despite being much more expensive than some competitors, they sold tons of it. Do the math.

    1. Vinish Garg


      I cannot agree with your comment as “As long as the reader is pleased by his reading environment, he is much more forgiving in regards of navigation, content and correctness.” as much as I disagree with “People react completely different to the same person wearing either a suit or rags, despite the same character is behind it.”

      We react differently to the same person at our first instance. On our next and subsequent interactions with the same person, we disregard the suit or rags. Same applies to documentation.

      A comfortable reading environment can be a good add-on for the reader; it cannot and should not be at the expense of accuracy or correctness or comprehensiveness of content.

      1. Mark Baker Post author

        To which we might add that someone is far more likely to give to a beggar dressed in rags than to one dressed in a suit. Dress is all about occasion. If we dress technical content like advertising content, people will take it for advertizing.

        Dress is a part of staging — though it is not the main part of it — but the right dress for staging is not as dressed up as possible, it is dressed appropriately for the role.

  4. Mark Baker Post author

    Thanks for the comment, Alex.

    But I disagree. Staging is not about eye candy. It is not about font choices or graphic selection, or any of the decorative aspects of text. Yes, that stuff matters, at least in some cases, but a well decorated house is not a well staged house. Making the page visually appealing is not staging content.

    One of the reasons that staging a house is an apt metaphor for content is that, unlike most purchases, a house is a purchase that always raises the question of how much work has to be done. This is why you stage a house to make it look “move-in ready”. The potential buyer is thinking about things like how much work they would have to do to make the house ready to live in — how many walls to paint, how may curtains to buy, and how much work they will have to do to clean and maintain it. A clean sparse layout gives the impression of less work to be done.

    Real life requires more work and more stuff, but that is not the impression we want to give when we stage our house. This is why a staged house is hard to live in. It is not stage to make it look easy to live in. It is staged to make it look easy to clean.

    Similarly, when someone browses a catalog, they are thinking only of the pleasures of ownership, and the prestige the purchase of the object will confer on them. Making the page visually attractive reinforces this sense of pleasure and prestige.

    But when it comes to technical communication, the user, like the house buyer, is anticipating work. They are anticipating work to understand what the documentation says, and they are anticipating work to actually accomplish the task. Of these, it is probably the learning that they dread the most. The expenditure of mental energy — particularly on that most taxing of mental tasks: learning something new — is something we are predisposed to avoid.

    Just as staging a house is about minimizing the amount of work the buyer imagines when they look at the house, so staging content is about minimizing the amount of work that the user imagines they are going to have to do to understand the content and accomplish the task.

    There is no particular reason to suppose that, beyond basic readability, sophisticated layouts and font choices are going to accomplish that goal. This is something that has far more to do with the organization and structure of the content itself, rather than with its presentation and formatting.

  5. Tom Johnson

    Interesting thoughts to consider. I remember how, in my previous job, one of the product managers felt we really had outstanding documentation simply because it looked great. I don’t think he’s read much of it in detail. It really did look sexy, with custom Drupal styling and development.

    I want to be sure I understand what you’re recommending. Are you saying to reduce some of the apparent complexity of the help by slimming down the TOC and embedding the links directly in pages? For example, suppose this is one TOC section (on bike maintenance):

    Adjusting brakes
    – Removing brake cables
    – Fixing stiff cables
    – Replacing brake pads
    – Tightening brake distance
    – Adjusting spring tension
    – Making mIcro adjustments on the fly

    Rather than have all of these topics in the TOC, you recommend maybe just having the heading in the TOC and then embedding the other topics within that topic in places where relevant?

    I remember reading a bit about second and third tier navigation in some information architecture books I was reading a while back. Certainly, almost every tech comm tool out there creates an enormous TOC with every topic selectable. Very few have the third level hierarchy separated out into an on-page navigation experience. Yet most websites present information this way. It’s not until you hit a page that you see more options associated with the topic.

    It would be interesting to see more research done with the way people use help systems. How do we know people *don’t* prefer to scan the topics in the table of contents like this?

    1. Mark Baker Post author

      Thanks for the comment, Tom.

      This post is more about making the case that we need to stage content better, and pointing out that conventional help is not good staging. I will be making some posts on concrete staging ideas later, but I don’t think I have any monopoly on coming up with good ways to stage content. (Criticism is easier than creation!) I’m hoping other people will suggest some great ideas.

      A couple of things I do often suggest, and that might apply to your bike example (depending on context) are:

      * Don’t show the TOC in a separate pane on the screen (fundamentally bad staging). If there is a TOC, provide a link to it (usually top left, next to the home link). This is basic decluttering. (It does, of course, suppose that the topics are capable of standing alone and establishing their own context — that is fundamental to this approach.)

      * If the TOC is collecting a number of tasks under a common category — “Adjusting brakes” in this case, don’t just have that as a category in the TOC, create a topic on adjusting brakes. This would generally be a pathfinder topic and would connect the rider’s real world issues to the specific features and tasks.

      * At least one of the tasks here would also apply to adjusting the gear selectors — Fixing stiff cables — so it could be linked to from a pathfinder on adjusting the gears as well as from the pathfinder on adjusting brakes. This is reuse by reference (which is good for SEO, as we have discussed before).

      For the TOC itself, a less daunting and more reassuring TOC might be created by just listing the pathfinder topics and letting the user find the individual task topics via the pathfinders — though that is only one possibility and depends on who the audience is and what terms they think in when they look for content.

      There is, of course, more to a bottom-up architecture than demoting the TOC. Every page in the collection should also be an Every Page is Page One topic, with all of the appropriate context setting and subject affinity linking that that implies. The whole point of a bottom-up architecture is that the topics themselves are the primary form of navigation (as in Wikipedia, or Amazon).

  6. Ruth Haworth

    Hi Mark – Great post.

    Years ago I read a description of a PhD thesis that studied retention of info in technical documentation and found that people retain info better if the reading experience makes them happy. I believe they controlled for how much the reader read; this was simply retention.

    I have always wished I could write my developer docs to be like Dummies Guides. I used to have a book called, I think, The Idiot’s Guide to Java Programming, that I loved reading. Notes and tips were put in boxes with a cartoon of a woman shouting, “Hey Stupid!” I would leaf through just rereading those bits because that Hey Stupid was so delightful. (Maybe you have to see it to get it.)

    Several years ago I judged a book at the international STC conference that was a delight to read. In fact, I argued it through to best of show; I’ll try to find it. It was written for psychiatrists who are treating patients with… ?… bipolar disorder I think, and it was full of recurring special items on pages: a case study written up as a diary, glossary terms, etc. Again, it was a delight to read.

    These are book examples, but we could be so much more creative and playful in our approach to documentation. Not that it’s easy.

    1. Mark Baker Post author

      Thanks for the comment Ruth. Sorry that it didn’t show up for a couple of days. For some reason my spam filter didn’t like it — can’t imagine why.

      It makes total intuitive sense that people retain more when the content makes them happy. Confirmation bias would simply be the flipside of the same coin.

      One of the things that I keep harping on in this blog is that readers of tech comm are under stress. They were trying to get their work done and they were stumped by a problem. That’s upsetting. It stretches your mental resources to an uncomfortable level. It makes you mad. That is the state of mind that our readers are in when they reach our content.

      Content that makes them happy is going help put them in a better mood, and that should help both their retention and their comprehension and task performance.

      But it can be a bit of a high wire act. What makes one person happy can just annoy another person. I have a book called Head First Java on my shelf which is similar to what you describe for the Idiot’s Guide to Java Programming. I find it incredibly annoying.

      That might just be because one book does it well and the other does it badly. Or it might be that some people like that stuff and other’s don’t. Perhaps the approach to staging needs to be different when you are one contender in a crowded field as opposed to the sole official source of information.

      Frankly, I’d be happy if we got to the point of not creating even more stress for the already harried reader.

  7. Pingback: The Content Motorist » KB Case Study: Pain Points and Analysis

Leave a Reply