Simplicity in a 550 page manual?

Simplicity in a 550 page manual?One of my readers, Shweta, asks the following question:

I am a Technical Communicator working in a software services company in India. I have been reading your posts daily from a long time now.

I am developing end-user documentation for an access control product. The current application that I have is huge and so is the user manual (550 pages, which I am sure not even 55 users will read). It also has an over exhaustive online help (not context sensitive, unfortunately). A Quick Reference Guide (prepared for each of the applications; there are 5) is still not sufficient to let the user know everything.

Was wondering if you can guide me on reaching best to the users with simple documents.

I’m opening this up this question to the community for response. You can add your thoughts in the comments below.

Here’s my take on this situation.You have the right approach in creating several quick reference guides to accompany the longer, 550 page user manual.

However, don’t expect the quick reference guide to cover the same scope as the long manual. There’s no way that you’ll teach users all they need to know from a 550 page manual in a few quick reference guides. That’s not the point of quick reference guides. The point is to help get the user started, to introduce the user to the content in an approachable way. Learning takes place primarily from doing, so the key is to get the user exploring the application quickly. Give them some direction and guidance to begin. That’s all a quick reference guide needs to do. See more from me about quick reference guides.

Madcap FlareAdobe Robohelp

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.

  • Phil

    i. Don’t document the system; document the tasks. Think about what users will want to do with the programme, then explain to them how to reach their objective.

    ii. Provide links/reference to more detailed technical information for experience users.

    iii. Provide a comprehensive ‘when things go wrong’ section (i.e., troubleshooting guide), but keep your solutions structured as step-step task/tests to complete to get back on task, rather than technical explanations.

    • Chris Ninkovich

      I agree with Phil.

      Also, have you considered developing some short training videos?

  • Noz Urbina

    First off – I agree with eveything Phil said:
    Task orientation with links to additional related content where necessary.

    Additionally, I would suggest formally getting trained up in Minimalist and modular writing.

    The terms that I would look into online for educating yourself are:
    – Minimalist writing
    – Taxonomy
    – Information Architecture
    – Content Modelling

    These will often be about web content/websites, so if you add something like DITA or XML after them, you’ll get webinars and explanations that at least are (usually) focussed on technical writing rather than say a marketing-oriented website. The principles of taxonomy and content modelling apply regardless of the storage format (which is all that XML is).

    The most effecient for your users is going to be if your content is as consistent – both in terms of content, terminology and structure – as possible and there’s little mixing of information types as possible. In strongly typed standards like Information Mapping or DITA there are discrete templates for conceptual, procedural(task), and reference (data) information. It’s key to not mix these. It’s often easy to whack a little reference table into a task step. The user might need to know a set of parameters or options, so you stick the content right in there, or you start explaining a concept because that step is the first time it’s come up.

    Don’t ever do that.

    The user isn’t always new to the system. Often you’re going through the manual not because you’re learning to use the system, but because you’ve simply forgotten something – a fact you need to reference or the specific steps to carry out of a procedure. In both cases you want to be in and out of the documentation as fast as you can.

    For your own part – If you want to maintain these 6 guides and not go insane, you’ll want to make sure that the big guide is a superset of information and the smaller guides can be cleanly extracted out if it without giving you 6 places to make updates instead of one. There are lots of ways to do this, I’m a big fan of DITA XML, but it’s not the only way to work.

    – Noz

  • Noz Urbina

    PS – If you can, do a formal User and Task Analysis. The best way to prioritise and then minimalise content is actually to do a study that actually tells you what content your users actually use, vs. what is there “because it’s always been in the manual”.
    – Noz,

  • Anne Sandstrom

    I agree with Phil. It’s not how much information there is, but how easy it is to find. Also, are there “layers” of information? If so, incorporate that into the navigation. And, btw, I don’t think 550 pages is all that huge.

  • John Melendez

    I’ve come up against Shweta’s same dilemma previously, and here’s how my team worked it out.

    A long-form 500-page doc is good for users who are used to working with a table of contents in a printed doc, or searching a PDF for a keyword. Go ahead and make docs like this for this first kind of audience audience. Otherwise, there are two additional ways to to address the issue.

    The next method is to create new docs that support common workflows. For example if you have a nurse using a medical device, and their role dictates that they are allowed by law to perform only certain tasks on the device’s software/user interface, then develop documentation specifically purposed to address their workflow. This can be delivered to the user usually as a printed workbook, a short job guide, or as a PDF.

    The last common way to address this is to provide context-sensitive end-user help that can be invoked by clicking a help button on the application screen in which the user is currently working. The help that pops up has only to do with that screen’s features, and thus eliminate the need to sift through an entire manual. If they wish, the user can click on to other links if that screen’s help isn’t what they need.

    Implementing context-sensitive Help requires some collaboration with the application engineers, as they will need to create code that will cause this context-sensitive help to pop up. The engineers also need to be able to find a way to easily deploy Help content updates, should you find areas in your Help content that require updating, or are inaccurate and require correction

    In creating user documentation – and deploying it – use what works for the audience you have in mind.

  • AMG

    I agree with the task based learning. I face a similar dilemma with a medical software. Instead of focusing on what the software can do, I decided to approach it from their roles and how they use it. My path was clear, very quickly, in fact.

    good luck!

  • Ketan Sevekari

    What Shweta says about not even 55 writers reading the help is true in our company too. Last year I was working on a major release of a product and I was working on the installation scenarios. This is one of the 35 documents I had to work on for the release. I had spent a considerable amount of time working on these scenarios and almost done with all the changes when one day the SME told me, “We are updating this document, which is good, but nobody actually reads it”. That was the most horrible moment of my life. But what he said is true. Our company also has a big services team which assists users. And the customers just by pass the docs and call up the services people which is easier for them to do rather than going through pages and pages of pdfs.
    How many people really like using pdfs? To be honest how many of us are ever interested in reading and finding information in a pdf if it is given to us?

    My point is why we are still stuck with the traditional forms of help, such as the PDF or an occasional chm. One reason I always get when I argue on this point is that people might want to access help when not connected to a network, or that people can print a pdf like a book and use it.
    How many people really print a manual? And is it wise to do so…when all companies are supposedly going green?

    Google has made the text box and a search button (now even that is not required with Google’s instant search feature) the de facto standard of searching for information and for many of us searching that way has now become a reflex action.

    Then how can we expect that the help we are delivering in the form of PDFs is at all intriguing to use?

    My take on this is it is high time we revisit all traditional forms of help and carefully scrutinize whether they are really relevant, or whether we can have a simple web based help system (like a wiki) that can provide an easy and interesting way of accessing help.

  • Rengaraman

    1) Try to include “What’s new” section(hyperlink) from the product to your online help. Existing users will be interested on this area as they already knew the old things in your application.
    2) Create or update the quick reference cards for these new features included in your product.
    3) Create some screen casts or video training tutorials for these new areas. (For this, budget matters)
    4) Co-ordinate with the application support team to find the common queries that they get frequently and concentrate on that by creating some short FAQs.
    5) Try out the possibility whether you can interact with the customers directly or via project maangers to understand their needs (This won’t happen, nothing wrong in trying out).

  • Bob Chapman

    Has anyone asked what the users need and want? Who are the users? What do you know about those users?

    I wanted to start in with all sorts of things I would do if this was mine, but I kept asking of who are the audiences.

    Note that I used the plural. Audiences.

    I said audiences because of an assumption I made. I assumed that the current manual is a catch-all for everyone from the end user, through the system administrator, all the way to the sales representative selling the product. I could be very, very wrong.

    The most important thing is to get a grasp on the basic question all writers should have: who is my audience? Once I have that answer, other recommendations could flow.

  • Roger

    I would really think about ways to reduce the manual. One suggestion is to split it into two documents, one for ADVANCED USERS. Another is to reference the online Help for specific taks rather than duplicating information.

  • Melanie Blank

    Thanks for this post,* Tom, and thanks to others for excellent comments!

    *the related posts link to information about quick ref. guides is really helpful, too.

  • Mugdha Kulkarni

    Interesting discussion!

    I agree with most of the comments. Wonderful responses. Clearly, user needs are not identified if not even 55 users are reading your manual. User needs are mostly based on the user tasks. Prepare a task list, and then plan your documentation. Base your information architecture to address all the user needs and to cover all the user tasks. Your documents will be much more usable that way.

    When we talk about information architecture, many writers think of only the Table of Contents. No, you need to think of the bigger picture. For each topic, try to guess when the users would want to see it, and how they will search for it in the doc set. Then you’ll know what to include in PDFs, what needs to go in the online help, and how compact your Quick Reference Guides need to be.

    A huge doc-set is not the real problem. Information organization is.

    Ketan: I disagree with most of the content of your comment. Any online help does not need to be intriguing or fascinating. It need not be traditional or path-breaking. All it needs to be is “helpful”. You take that one feature out of any technical document, and it loses all its charm.

    This is a topic in itself. What say?

    • Tom Johnson

      Mugdha, your comment here “A huge doc-set is not the real problem. Information organization is.” is what inspired my whole series on content organization.

      • Mugdha Kulkarni

        Hi Tom,

        I am impressed that you’ve written Twenty-Nine(!) articles in this series. It’s one of my favorite topics, and I am looking forward to reading the entire series in the next week. (I love this Christmas shutdown!)


  • Radiant Dawn

    Making myself in the situation! I’m expressing my thought, your suggestions and critics on my thoughts are welcome…

    Although this product has some vast information and needs 550 pages of help documentation, the product that I’m representing is for satisfying some basic needs / requirements of the end users.

    I try classify the information in the so-far claimed writing tool “Pyramid” style; Priority basis to satisfy the end users forever. Most important information first, followed by the less priority information. In this way I can make sure that both new users as well as existing users can find the information that they required.

    As in the manner that the new users will find the most important information first like, how to use the product; purpose of the product; getting help for the product; functions of the product and so on, and the supporting information like features; utilities; benefits of the product and so on, when user need it and the existing or experienced users can find the supporting information first then refer to the important information whenever they need it.

    I organize the information in first priority basis and in a rhetorical strategy between information contained in the documentation, so that users can not miss out any information that has to be known. Obviously in this way not any user can escape from unknowing the information about the product.

    Writing about the Reference guide:

    Reference guides are needed & useful for the existing / experienced & intermediate users more than the new users, not all the users need the reference guide all the time. Making short & concise explanations about the product, sorting the reference in an ascending order and directing the readers to the explained and reference topics, makes all type of users to make use of the product reference guide.

    In simple, my words are, will try to make the user first to use the product and let the user to find and solve the difficulties that he / she experiencing while using the product, not try to educate the user professionally before trying out the product.

  • Jonatan Lundin

    One very important, fundamental, task for a technical communicator is to identify the audience, as discussed in this thread. But there are several challenges in identifying the user(s), especially for products on a global market. What is a user? Let’s say that we would put all individuals, which at some point are using our product, in one basket. What factors define if these individuals shall be grouped into several audiences? How do we distinguish one user group from another?

    I would be interested in hearing how others have solved the challenges I’m facing. Read about my challenges in