Sticking with Obvious Information Versus Creating Information that Users Need

In my recent tech comm poll about why users can’t find information in help, one of the top answers was the following:

The answer isn’t in the help because the help sticks only with obvious information.

No doubt at some point in your life, you’ve clicked a help file and browsed around only to find that the information is too basic and simple to answer any real troubleshooting questions you have have. Through repeated experiences like this, many people come to believe that help is generally useless.

For example, when I do WordPress consulting for websites, one of the most common problems is figuring out why the chmod settings for folders on web hosts don’t take effect when applied via FTP. If WordPress can’t write to a specific folder, it can’t do things like update plugins or update the version of WordPress. Yet whenever I venture into help material for cPanel or Plesk or whatever platform these web hosts have, the question is rarely answered.

This is just one example where I fail to find the right answer because the help sticks only with obvious information. Each time I end up empty-handed in help, my confidence in clicking the help button in another system decreases.

Surely if people could just find the answer in help, no matter how deep it was buried, the experience of help wouldn’t be a downward spiral. Is the problem that tech authors are sticking with obvious information and not covering the more advanced troubleshooting and power techniques that users want and need?

Categories of information

When we talk about missing information, it’s easy to label the information as advanced or non-mainstream — in contrast to novice or beginner type of information. But I’m not sure these labels are particularly helpful. We never write “advanced” information for the sake of writing advanced information. As we document a software program, we wouldn’t seek out the dark corners of the app and complicated workarounds in the hope that more advanced users might find this information useful.

The question for the tech writer should usually be as follows: What questions or goals does my user have, and are those questions or goals answered in the help? In other words, it’s a best practice to start with the user. What types of questions are users asking, what types of questions are coming into Support, what type of problems are users having, etc. That should be the focus — not beginner versus advanced.

Real Scenario

Of course, it’s much easier to state general principles than actual problems, so let me paint a more realistic picture. Creating help material gets tricky when you consider that your audience has a variety of skill levels. What is obvious to one person is not obvious to another.

For example, let’s say you have two main types of users: developers and marketers. Both types of people use your software in different ways but with similar goals. For developers, there’s an API that allows them to customize information in more advanced ways. For marketers, there’s an interface that let’s them grab code snippets to add information to pages.

It’s easy to write for the marketing audience but much more challenging to write for the developer audience. How far into programming code can you go? Will documentation answer all the difficulties that developers are likely to encounter, not only interacting with the API, but in leveraging the API to create functional code and attractive output inside their web applications?

Usually API documentation does not explain fundamentals of JavaScript, PHP, HTML, CSS, or other programming languages. One assumes the audience is savvy enough to work in these languages, and hence does not need methods, functions, objects, and such explained. You do not have to write things like, “The JavaScript code block must be enclosed in script tags,” or “The .push method adds the item as a new item in the last position in the array,” or even that a convention like $("#myDiv").click is a jQuery event listener that triggers when a user clicks the element with this ID.

We skip over explanations of the basics and instead assume our audience knows all of this. But at some point, the help will tire out and fail to cover all the challenges developers will face. How do you render components dynamically on page load, integrating external libraries asynchronously? How do you create an infinite scrolling widget that loads quickly and contains a scroll bar with a size that adjusts gracefully as new information is added to the widget’s data?

For this type of information, developers are on their own. As technical writers, we usually stick with the basic call patterns and methods supported by our API. But if we do this, do we shortchange our users who foray into help looking for more advanced answers?

The Flip Side: Not enough information

Now let’s flip back to the marketers. Suppose your marketing users complain that the documentation for using the API is too confusing. A tech savvy marketer wants to customize his or her widget, and so has figured out how to call (sort of) the API to pull down the data he or she wants, but now faces a number of challenges. The marketer wonders, what are these references to dollar signs and hashtags ($(#myDiv)). Where does this JavaScript code go? And what is the whole .push command doing?

Is it your job to write documentation at a level an unskilled user can understand? Do you have to dumb down your developer-level instructions so that marketers can understand and follow them?

If marketers need a basic introduction to jQuery, JavaScript, CSS, and HTML, they’re clearly a long way from understanding and leveraging your API for any development. If this is the case, it’s unlikely they’ll find the help useful. You could explain all the code, but then you would be left with a novel of information instead of the more succinct code instructions that developers prefer.

These are the challenges with documentation. Users are invariably at many different technical levels, and it’s impossible to fully know and write for them all in a way that meets every user’s need. This is why it’s imperative that technical material allow users to skim and skip around, so they can go to the information they need and skip over the material they already understand.

The variety of skills levels among users is why technical writing differs so significantly from literary writing. In literary writing, we expect that users/readers are usually on the same level of awareness, and won’t be skipping around. Not so with technical information. With technical information, a user might read just one sentence on an entire page, while another user reads the entire page and follows every link.

Real reasons why advanced information is absent

Fortunately, by including subheadings, links, search, table of contents, etc., you can allow users to go right to the information they need (if it exists). The beginning users can read the introductory conceptual material while the advanced user can search for a particular error messages and resolution. The problem isn’t so much one of organization, because if the answer is in the help, search will often find it.

Most likely the real reason more advanced information is absent from technical material is that it’s much harder to come by. A topic might take an entire day to figure out, after testing and asking various engineers questions. After all of your investigation, you might have just one little note or paragraph. If you spend 10 hours finding one answer, your to-do list piles up and you might have trouble meeting deadlines. No one has infinite bandwidth to create endless documentation that meets users’ needs at every level.

Another reason the advanced information might be absent is because the information is beyond our own skill level to document. This is especially true with API documentation. When you write for programmers, you have to develop a knowledge of programming to provide insight at the level that users might need. That’s tough stuff. For example, coming back to the widget with infinite scrolling, I might be able to tap into a jQuery plugin to make that happen, but I’m light years away from “rolling my own,” as they say.

Another reason help sticks with obvious information is because we may not be equipped to find it. We may be documenting something that we don’t have access to. Consider the challenge of documenting a storage network array, or some technical product that you don’t have direct access to. In many cases, you’ll have to rely on engineers for information, and if this is the case, you’re at the engineers’ mercy to define the information needs of the user.

Another reason help is silent on more advanced topics might be the division between decision support and technical support. If the information users seek includes strategies on how to use the product in a particular business scenario for maximum impact, it’s unlikely that help is going to address those needs.

For example, my company’s product involves gamification, and there’s a lot to know about what techniques work in different situations for different industries and goals. It’s currently beyond my role to recommend implementation strategies. For that we have specialists who looks at the user’s business environment, goals, and match up techniques that will work best.


I hope I was able to shed some light about why help sometimes sticks with obvious information. Getting the right information into the help material is not an easy problem to solve. It is perhaps the problem to solve in creating help material, as the type of information we write depends on the alignment of so many factors — input from other groups, demands from product managers, legacy expectations, our own sense of information needs, the variety of skill levels among users, and more.

How have you been able to gauge your audience’s information needs to go beyond obvious information? If you lean towards more advanced instruction, how do you avoid alienating your lower-skilled users?

Adobe RobohelpMadcap Flare

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

  • craig wright

    A good summary of the problem…although there is another reason why help can be lacking – the powers that be don’t understand what end-users actually need and limit your brief to writing only the basics. I’ve seen that happen, even though there was opposition to it. It’s not always the tech writers that make the decision, is it?

    In a large company I used to work for, there was a small team of tech writers working on a very complex software app. To deal with that, the work load was prioritised according to what the projects engineers on site said customers were struggling with/needed to set up first. It was the next best thing to being able to have direct contact with the customers and it worked well – the basic/self-explanatory parts of the product were not documented in full until 2-3 years after the release. Instead, we created an online tutorial that covered much of the same stuff as the training courses (so used a lot of the same content) and that dealt with a lot of the more basic questions in the short term. The tutorial gave customers an idea of how features were implemented, so they had a good chance of figuring out other simple-mid level features on their own. With the tutorial covering the main areas of the product, the documentation team had more time to dedicate to the more complex features.

    • Tom Johnson

      Craig, thanks for sharing your experiences. I like how you triaged the work through the insight of on-site engineers. It does seem odd that a product wouldn’t be fully documented for 2-3 yrs after release, but I can see how that might happen. A startup doesn’t recognize the need for tech writers until they hit the crisis point — and then it’s a matter of playing catchup.

      • craig wright

        Oh, it wasn’t a startup – it was a company that had been around for 80 years! It was just that the first versions of the product were out with customers before the documentation effort was started. Development and sales resources far outstripped documentation resources (2 authors, 10-15 software developers, lord knows how many sales staff around the world).

        It comes as a relief to hear that the importance of documentation is overlooked on both sides of the pond.

  • Greg Babb

    I second what Craig said – and add that the reality of tech writing is that you struggle to document basic user topics within the product development cycle. It’s often a changing product at that, and by the time the manuals are published you feel lucky that you even covered the basics. Then a follow-on version of a product with new features is planned, and the whole things starts over.

    Due to tight budgets and time constraints, most tech writers end up only documenting the obvious stuff. I too wish that more useful topics could be added.

    • Tom Johnson

      Greg, good point about just barely having bandwidth to cover the basics. In theorizing about tech comm best practices, we often operate on the assumption that we have infinite time to do everything, but the reality is that we only have a few hours here and there and so must do the best within that time frame.

  • craig wright

    But we must fight that reality! We need to skip over the basics and use our time more efficiently. The tutorial I mentioned was a great way of doing that – a quick step-by-step tour of the product basics, and then the majority of the documentation effort was spent on documenting the more complex tasks and concepts properly. The key to all of this is:

    a) Being able to recognise what is basic

    b) Being able to prioritise the complex tasks that are needed as opposed to those that would be nice, but aren’t key things things that customers are struggling with

    c)Challenging the powers-that-be when they instruct us to ‘just cover xyz’. We need to fight on behalf of the users and point out the folly in only covering the very basics/providing insufficient info on complex features.

    • Tom Johnson

      Craig, thanks for sparking the discussion. Speaking out against a product manager’s decision to only document xyz seems like a tough sell. Don’t we assume that the product manager gets good info from users and acts in the best interests of the product? Ultimately isn’t the product manager the one who owns the decisions about the product? I know the product managers are often short-sighted about documentation efforts, but it’s hard to oppose them without presenting hard evidence that they’re wrong.

      • craig wright

        Well, there is always the counter-argument of ‘where’s the hard facts to prove they are right’. In my experience, the product managers have very little understanding of documentation, other than knowing something is needed. I was chatting to another freelance tech writer about this recently, and she said she often has to tell clients to just trust her professional opinion – if they do, things turn out well; if they don’t, she ends up going back after they have had negative customer feedback.

        If worst comes to worst, you can always use input from other departments to back your case. When you are right, there are usually others who will agree with you and chip in. And if you really have to do the basics, make it known you disagree with it and are doing it under duress. At least that way you have some credibility when it comes back to bite the company on the behind.