How non-programmers use documentation.

Posted 8 Nov 2001 at 16:22 UTC by kevindumpscore Share This

Here are some observations about what would make documentation friendly for non-programmers.

I've tried to give back to the Linux community by helping with documentation. I've helped with some FAQs, HOWTOs, and am working on a large reference manual. Lately I started wondering how non-programmers actually use documentation so I asked a few.

I'm not trying to write a doctoral thesis so my process wasn't scientific. My information is based on informal conversations with friends and co-workers. Here is what I learned about how non-programmers use documentation.


  1. Non-programmers insist that context-sensitive, on-line help must be provided with an application.
  2. Non-programmers want screen-shots in the on-line help. They don't care if it increases an application's file size.
  3. Non-programmers utilize on-line help as a quick reference, so indexes and search functions are important.
  4. Non-programmers will go through an on-line tutorial, if one is provided as part of the application.
  5. Non-programmers will look at a "Tips and Tricks" dialog box, if one is provided.
  6. Non-programmers ignore the printed manuals bundled with off-the-shelf software.
  7. Non-programmers would never buy a book about an application. They say technical books are for programmers.


  1. Non-programmers don't want detailed explanations, they want simple answers.
  2. Non-programmers hate too much detail.
  3. Non-programmers prefer short, step-by-step instructions.
  4. Non-programmers prefer information that answers the question "How do I do X?" (where X is a common use of the application).
  5. Non-programmers don't want to see information about how a feature was implemented.


  1. Non-programmers assume that on-line help will be updated in each new version of an application.
  2. If part of the on-line help is obsolete or missing, non-programmers will not use any of it.
  3. If a non-programmer can't find an answer in the on-line help, they will either call tech support or use another application.
  4. Non-programmers that I talked to have never sent a bug report or a feature request to a software company. The idea of sending one directly to a programmer or a technical writer was a completely foreign concept.

Good primer, posted 8 Nov 2001 at 17:20 UTC by MikeCamel » (Journeyer)

Nice one. I've spent some time writing documentation for commercial projects in previous lives, as well as some reviewer's guides, and I'd say that the latter are a great way for people to start to think about how to write documentation.

Let's assume that you want someone who works for a magazine that you value to review your product. They have a pretty good idea of what's what, but on the other hand, they have very little spare time, and they're not going to spend any of it trying to second guess your instructions. If it goes wrong, or doesn't do what they expect, they'll throw in the towel, and you've spent a lot of time on that towel, so you don't want that. You need to write a "how to install the software, and then access the most impressive/important features it provides" document. You need step-by-step instructions, with one step per instruction. Multiple instructions on a line will get confused, and won't work.

You need screenshots - in fact, window-shots, even of shells, are often even better - at key points, so that they think it's worth continuing. They won't bother if there are 30 instructions with no breaks - how can they be sure that they've done the right thing without a picture?

Last of all, you need to sanity check your instructions. First, get someone who knows the software pretty well to check it for brainos and/or typos. Then get a moderately experienced user to try it. Then, if you can, get a user who knows a different version of the software to try it, to see if they make unwarranted assumptions, or if you have. Then get a brain-dead user who's never tried it before to try it. Not your Mum (unless she's pretty computer-savvy), but someone in your dorm, or at work, or whatever.

Then fix the problems. You'll find lots (or your poor testers will!), but next time round, it'll be easier.

Writing docs for consumer products (and we're seeing more and more of those in the OSS world, which is good, right?) is hard. It's a job for specialists in the commercial world, and where we can, we should recruit those people to the OSS world, too. Failing that, we've got to learn to think like the poor saps we're writing the software for.

We can always put our brains back in later.


Make "How do I" your mantra., posted 8 Nov 2001 at 18:43 UTC by cmacd » (Journeyer)

I don't know how often in my work life, I have opened an help file, which is indexed the same way as the menu bar, File Edit Foo Bar ...

If I am in Help, I want to know how do I change the font, or How do I import my bookmarks - Restated as "how to I put my bookmarks into the program" by those who don't have a beard as long as mine.

A user is unlikely to have much patience with your program if they can't figure it out, and they will just tell their friends that It is Broken. or Alpha quality if the feature they need is hidden away in a deep dark drill-down menu item.

Standardization across applications, posted 9 Nov 2001 at 04:28 UTC by Ilan » (Master)

This probably goes without saying, but on-line help should be standardized across applications. When this is done, once a user knows how to use the on-line help in one application, they know how to use on-line help in every other application.

Other elements of good documentation/design

  • The more modal a help area is, the less effective it is and the less likely it will used.

  • Programs should not have a menu titled "Help" that doesn't have anything that actually helps the user (i.e. Don't call it "Help" if it only contains "About" and "Release notes").

  • Searching for words in online help should be raw text searching. No searches using artificial intelligence crap that tries to substitute for the real thing (like we often see from a company in Redmond Washington). For example, if there is a word called "crop" used in some area of a program, a user should be able to type "crop" in the search box and every damn help page on any area of the program that has something named or labelled "crop" should be brought up.I've seen way too many applications written by the clueless folks at Microsoft where there is something called called "Feature B" and the only way to locate info on "Feature B" is to type "How do I do thing Q?" And sure enough, under the help screen for doing "thing Q" there is the string of text "Feature B". Don't pull a Clippy.

  • Tooltips (sort of a form of micro-documentation), while useful, are no substitutes for labels. Anything that is tooltipped should absolutely be labelled, no exceptions. Three seconds waiting to understand what something like a toolbar button does are three seconds too many. Don't pull a KDE.

  • Written documentation should have lots of examples, especially examples relating to different situations or variations of a problem. Don't pull a HOW-TO.

Documentation is useless., posted 9 Nov 2001 at 07:38 UTC by ali » (Apprentice)

I worked as sysadmin for quite some time, and part of my job was sitting in the computer lab, helping users if they had problems. Visitors were math or engineering students doing programming or unix courses.

I did believe in the idea "Good documentation can help users solving tasks", and so I (and the other team members) wrote lots of documents for everything. So, for example, after the "how to log in, log out, change password, browse the web" lesson, the users got one-page summaries of what they learnt in the previous 90-minute lesson, and were sent to the computers.

After watching that for some years, I learned that documentation is completely useless. One of my key experiences was the following: One user came and said that his computer was broken. I followed him to the computer and he showed me the assignment he got. It read "Create a file called groupmembers, and write your name into it.". He took the mouse and clicked into the xterm, to show me the xterm didn't open the file. (He did not click on a text "groupmembers" or anything. Just right into the plain empty area.)

So, I asked him whether he didn't get the according help document. He got it, but it didn't read it. So I instructed him to use it. That didn't help, so I pointed him to the paragraph he was supposed to read. It was:

"How do I create and edit a file? Let's assume you want to create a file called FileName. Then you type the following into the "xterm"-labeled window:

xemacs FileName &

Finish typing by pressing the Enter key."

He read the bold headline, then stopped. So I asked him to read the whole paragraph. He looked through it, then took the keyboard, typed "FileName" and hit Return. "There's an error", he complained, "I told you the computer is broken!"

Such experiences on daily basis for several years brought me to the following enlightenment:

Non-programmers do not read any documentation that contains more than about 5 words. Non-programmers have arbitrarily weird ideas on how something should be performed. If it doesn't work, they will first blame it on the computer, then on the program, then on the admin. They will not listen to any explanation longer than five words. If you stand besides them to help them, they want you to do it for them. If you do, they will see no need to watch what you do, they'll rather ask you every time to do it. In no case are they able to substitute anything in the documentation. If a login documentation contains the word "insert-your-username-here", they will type exactly that. If a screenshot for "Save as..." shows the correct image, but the "path" field contains "/home/admin/", they will detect the difference in their dialog, type the given path into it, and then complain the computer is broken. Anything written besides, below or onto the screen shot as explanation is ignored.

My favorite user managed it to ask three times a week for over two years someone to copy a file onto or from a disk. That's roughly 300 times someone showed him how to do it, but he didn't bother to remember it. (Then, all of us admins rejected to do it for him, so he cancelled his account and signed up in a different computer lab.)

Nobody reads bold, posted 9 Nov 2001 at 14:10 UTC by jooon » (Journeyer)

Good point ali, but you should remember that neither non-programmer nor programmer reads bold text. Especially not a complete paragraph. Perhaps a headline here, a word there, but not more. :)

What I feel is missing in most documentations is an introduction. What can I do with this program, and why? I usually have two options. Start the program and try it out and guess what can be done. Some non-programmers do that but not all. The other thing I can do is dive into the big manual, which describes everything in detail. No non-programmer do that. If I am lucky I use my third option. Read a review, written by someone who has nothing to do with the development of the program (like the relation between most non-programmers and their programs). Sometimes they have errors, or missing some of the most important parts of a program, but they are mostly adequate.

I can of course be totally wrong here, being a non non-programmer. :)

Users come in all Types, posted 9 Nov 2001 at 15:22 UTC by cmacd » (Journeyer)

While I am amused by ali's decription of some users, we should rember that computers are very imtimidating to some folks

My father in law for example needs documentation that would drive me crazy!

  1. click on the get mail icon
  2. press the return button (he can't double click consitantly)
  3. wait for the window to open
  4. when the "Connect to the internet" box comes up click on OK (he has win95)
  5. wait for the the box that says connected....

like your users he is bright, but he can get confused if we use a word that is differnt than what his screen shows.

His computer knowledge is brittle, if an error box comes up he has no way to recover.

he is also very Frightened of making a mistake and so he will not try anything other then asking for help.

A Couple Users' Experiences, posted 9 Nov 2001 at 19:30 UTC by goingware » (Master)

Here are how a couple users experienced their computers:

My friend's father was writing a book. This man was a retired college professor. He was not an unintelligent man. One time he had typed into his word processor for several hours without saving. He accidentally clicked outside his window so the Finder's windows came up (this on a Macintosh). He was frightened that everything had changed in his computer so he turned the power off and wouldn't use the computer until my friend came to "fix it".

When I was working at Working Software, I mostly programmed but being a small company I had to help out with technical support. One time a user called who was having trouble using our word processor QuickLetter. I asked him to select various menu items and press various buttons, but he just got confused. Finally I asked him what the title of the frontmost window was. He asked if I meant the big glass thing on his desk (meaning the monitor). After some questioning I realized that this poor fellow did not experience the various user interface elements in his programs as objects, rather he saw the stuff on his screen as an endlessly shifting, shapeless mass of confusing words and colors that had no cohesion. His experience was like that of someone who suffered brain damage, but to talk to him he sounded perfectly healthy.

My boss at Working Software (this was the friend above, Dave Johnson), told me that when doing tech support, I shouldn't say "click the OK button", I should say "click the OK button until it turns black", or "click the round button until a dot appears in it".

bug report == foreign concept, posted 10 Nov 2001 at 07:36 UTC by mobius » (Master)

Of course bug reports are completely outside of the realm of most people. In everyday life, do people call the manufacturer of their VCR when it breaks? No, because that would only lead to them being on hold for several hours, and maybe they'd get told to return it. So they return it/throw it out as soon as it breaks, without thinking twice.

It's the same way with a lot of commercial software. Sure, you can send a bug report, but chances are no one will ever read it, or if they do, it'll be months/years/eons before that bug gets fixed. In this case, most users reboot and try again.

Free software is the only place where there's a good chance of someone caring about your problem. And the average person doesn't know that.

Hmm, this was a bit OT. oh well. ;)

Documentation is useful, but only if you do it right, posted 10 Nov 2001 at 12:00 UTC by Ilan » (Master)

Ali, the from the examples you gave, if the admins wrote the documentation and set up the systems and the users blamed the admins, then the users would be correctly placing blame where blame lies. Don't take what I say the wrong way; I believe fixing the problem is more important than fixing the blame. There were several problem areas of the examples you gave that could be improved and make your users happier:

  1. "Create a file called groupmembers, and write your name into it."

    This assignment would make a lot more sense if it was put this way:

    "Write your name using xemacs and save it to a file named GroupMembers."

    Users don't first create files and then put content in them (at least not with most GUI paradigms in existance). They get started right away with using an application, and then after having generated some amount of content (whether that be 600 page novel or a single character) they save it to a file. Not that admins could do anything to change the confusing wording of the assignment, since that was the teacher's doing.

  2. A second part of your example also has a documentation flaw:
    "How do I create and edit a file? Let's assume you want to create a file called FileName. Then you type the following into the "xterm"-labeled window:

    xemacs FileName &

    Finish typing by pressing the Enter key."

    "FileName" is one of the worst names you possibly choose for such an example such as the one your gave. For technical documentation, if you as the author must give a name to something (naming a file, directory, string, whatever) in an example, and you can give it any arbitrary name you like, you never, ever want to choose a name that has some association with the task at hand because could be construed as some sort of "variable" that is to be replaced with a value. Or it could be viewed as sort of a keyword that is integral in performing the task. Perhaps the user you mentioned in your example thought that FileName was some essential command line argument that had to do with creating files (as opposed to actually *being* the filename), and the confusion is not at all that suprising; after all, the user *is* creating a file, so some command titled "FileName" is not theoretically impossible from their point of view. Arbitrary names should be arbitrary. As crazy as it sounds, using the word "kittens" as the name of the file would cause a lot less confusion than FileName. If you want something more pertinant than "kittens", you could have the person type their phone number in xemacs and then save it to a file called PhoneNumbers. There's a lot less opportunity for confusion or misinterpretation with this scheme.

    Another problem with

    xemacs FileName &

    is that it is not explained that xemacs is an application and not a system command (like ls, mv, etc), and does not explain that '&' is this optional thing that you put at the end of a command that will (from the users perspective) "spin off" the window of the application from the command line they used to create it. Saying "type these random things and don't ask why" insults the user's intelligence and will not lend the user a feeling of control of the computer. People don't like doing valuable work that is at the mercy of things they feel they can't control.

  3. Another problem that cropped up in your example was the mixing of paradigms. More specifically, the UNIX CLI paradigm and the current macintosh-type GUI paradigms. The terminal is a CLI interface paradigm and the Xterm window is a macintosh-type GUI paradigm. Part of the confusion probably stems from the fact that the user saw windows, a pointer, and a mouse, and immediately assumed the macintosh/windows interface paradigm was the paradigm for the system. And all of a sudden here's this interface inside the window that basically breaks the laws of physics for the paradigm they previously saw. Any time you try to mix one interface paradigm with another, bad stuff happens because you have to different interfaces constantly breaking consistency with each other. If the goal of the lab is for users to get valuable work done and produce documents using xemacs, it's best to leave the whole CLI stuff out of the documentation and out of the user's hair and simply add xemacs to the application menu entry, or if one already exists, refer the user to that.

  4. "If a login documentation contains the word "insert-your-username-here", they will type exactly that."

    This would be a lot more effective is it was shortened to username and italicized (i.e. username ), and then followed up by one or case examples a mythical user typing in a their mythical username and password. The login section could be rewritten:

    To log on to the computer, type your username and password at the login prompt

    790 login: username
    password: password

    For example, if Debby Malone's username was dmalone1 and her password was fuzzycritters , at the login prompt she would type:

    790 login: dmalone1
    password: fuzzycritters

    If Stanley Tweedle's username was stweedle3 and his password was helpmekai , at the login prompt he would type

    790 login: stweedle3
    password: helpmekai

Just remember your own goals, posted 10 Nov 2001 at 14:41 UTC by abraham » (Master)

Free software has different goals than commercial software, at least outside the intersection of the two.

What pleases users, both programmers and non-programmers, is goal oriented documentation. Documentation that allows them to use the software to achieve specific goals, without really bothering to learn how the software works. If you are writing commercial software, free or not, pleasing the users is likely to be a priority, and writing goal oriented documentation is therefore a must. The same is true for some motivations behind non-commercial free software, e.g. to promote free software over non-free solutions, or to experience the nice feeling of knowing your software gets used.

However, if your goal is to get qualified feedback, preferably in the form of patches or at least useful bug reports, ordinary users aren't going to be what you are after. As Kevin points out, they are unlikely to even report bugs. What you want is not users, but the much rarer power users. That is, users who actually have taken the time to understand the tool they are using. These users will use the tool in unexpected ways, producing interesting ideas for enhancements, give detailed bug reports, and if they are programmers, give the best kind of feedback, patches.

The goal directed documentation may lure some users to the tool who will later turn into power users, so it should not be totally ignored, even in this case. But the kind of documentation that helps create power users is not goal oriented, but tool oriented. Such documentation describes how the tool work, and the concepts it is build on, and should be supplemented by a (possible integrated) reference manual.

PS: This is my first post here. Hi!

Non Programmer documentation for dummies?, posted 10 Nov 2001 at 19:33 UTC by cullenfluffyjennings » (Journeyer)

"X for dummies" has been one of the best selling lines of books ever. Though the titles of these books insult me and I despise them, perhaps they provide excellent insight into what no programmers want in the way of documentation.

Reference sheets, posted 11 Nov 2001 at 00:11 UTC by mslicker » (Journeyer)

I was going down the list, and many of those things apply to myself.

I think it comes down to wanting to do something with the computer rather than learning the details of some application. Perhaps there is something we can learn here when designing applications. However, I'll save that for another discussion.

Documentation wise, I really like reference sheets. These are usually one sheet, extremely consise (very important!), and contain most if not everyhing you would want to do with an application. If you can't fit this on a single sheet it might be time to redesign the application.

Tutorials for common tasks are nice too. Could be combined with the reference sheet.

Maybe it's a matter of "usability" ?, posted 11 Nov 2001 at 01:08 UTC by premus » (Journeyer)

Would be maybe more interesting to find first what kind of user categories are out there. I know I found myself such users who had to write down all the steps for sending an email. But those users where maybe prime time computer users (I know for sure that they where) and it was a rare phenomenon. Not writing documentation at all because some don't use it is not a choice. Knowing well who are your target users might help you identify what kind of documentation to write. There might be no point in writing stories for experienced computer programmers but it would make sense to do that to casual computer users. So, identifying user stereotypes might be a good idea, but unfortunately a search on Google revealed no statistics but a couple of jokes and some research documents related to modeling user stereotypes. Anyway, maybe a good start to good documentation is writing it well. And here is a paper much appreciated on this subject. There also seems to be some ISO standards for writing user documentation:

  • IEC 18019
    Guidelines for the design and preparation of software user documentation
  • ISO/IEC 9127
    User documentation and cover information for software packages
  • ISO/IEC 15910
    Software documentation process
But then again, these documents are not for free :( Leafing about Microsoft is not a good idea. Usually these companies has put lot of money in usability and user behavior research and this is good. I don't use their help system (hell I don't even use their operating system) but most of the users do (how much of the desktop systems they own?) and even if some of them complain most of the users are able to use it. Some companies even publish the result of this researches so why don't we take the opportunity and learn something on their expense ;)

dummies books, posted 11 Nov 2001 at 19:02 UTC by mobius » (Master)

The "X for Dummies" books are actually how I got started with most of what I know. They gloss over a lot of details, but had enough examples and tips to get things working. Aside from the title, they don't insult the users intelligence at all. The style is casual and humorous, which helps the reader feel comfortable. I try to write my documentation in a similar style. (This also makes it more fun to write!)

Manuals and discoverability, posted 16 Nov 2001 at 14:02 UTC by emk » (Master)

Basically, I assume that the average user is either unable or unwilling to read even the shortest manual, and won't look at the online help.

Therefore, if you want the average user to use your software, you need to make it "discoverable". This means that they need to be able to figure out the interface directly.

This only works if your program adheres carefully to existing UI guidelines, and you do usability testing.

Good Mac software tends to do this better than Windows or Linux software. But since most computer users are Windows users, it's better to adhere to the Windows conventions, because anything else will confuse people.

Usability, posted 16 Nov 2001 at 20:23 UTC by mslicker » (Journeyer)

emk, I think you point what people design for today in software.

Most usability studies, I've found, focus on the initial reaction to the software, or the learning curve. Perhaps there are certain things that can be learned about human psychology in these studies, otherwise they seem to me mostly useless. Learning curve is but one factor in a design.

My hypothesis is that there is a direct relationship between the learning curve and user productivity, in well designed software. In other words, the more powerfull the tool, the more skill needed to wield it.

If the software is badly designed it possible to have both a high learning curve and bad productivity.

Thus, I think it is best to strike a balance between the learning curve, and productivity. To reach a sweet spot.

Copying Microsoft might lower the barier. For example, if someone is familier with Word, cloning Word in a free software word processor, might help this type of user. I don't see any long term advantages though. For me, Microsoft has not had even close to last word on how interfaces should be done. I find their software, with perhaps the exception of IE, mostly unusable.

New Advogato Features

New HTML Parser: The long-awaited libxml2 based HTML parser code is live. It needs further work but already handles most markup better than the original parser.

Keep up with the latest Advogato features by reading the Advogato status blog.

If you're a C programmer with some spare time, take a look at the mod_virgule project page and help us with one of the tasks on the ToDo list!

Share this page