Design Tidbits

back Tidbits Overview

Tools for Design and Visualization


Interaction Design

Screen Design


Visual Design

Design Process

Web, Web Applications, Web Design





How Much Documentation Do Applications Need? – A Simple Example

By Gerd Waloszek, SAP AG, SAP User Experience – January 17, 2003

Documentation and online help are often unpopular issues in software companies. They are regarded as superfluous – as something that costs money and human resources but provides nothing in return. But experience has shown that software that does not need documentation, is still a pipe dream. For huge software products, such as the SAP R/3 system, documentation is a major project in itself because of the sheer amount of text alone and its translation into many languages. Thus, every little saving on documentation pays dividends. The question is, however, how this reduction can be achieved. I cannot provide a general solution for this problem here; instead, I hope to offer some starting points for further thought. My proposal is, probably not surprising: Reduce documentation by less ambiguous user interface design. I will exemplify this point in the second part of the article using a simple application example.

Of course, my answer is only one of possibilities. Another valid answer would be that documentation writers should have a better understanding of their target users so that they can tailor the documentation more to the users' needs. We will have a second article on this topic from a writer and usability engineer's point of view.


Which Factors Determine the Need for Help?

Let's address the problem amount of documentation and online help required by looking for factors that determine whether and how much assistance users need when processing a task at a computer.


Complexity is often quoted as a "standard" measure of the need for documentation. But which factors actually determine how complex an application is? Simple metrics for estimating complexity are based purely on numbers: the number of particular screen elements, the number of screens that users can navigate through, the number of views users can select, and so on. Here are some concrete examples:

  • The number of input fields (including simple selection elements, such as dropdown list boxes, radio buttons, or checkboxes)
  • The number of tabs (views) in a tabstrip
  • The number of dialog windows that can pop up
  • The number of screen changes a user has to go through

What Do Numbers Really Tell Us?

On the other hand, when considering user interaction as such, handling a business application or Website is easy, as long as users have minimal knowledge about graphical user interfaces. (Without such a knowledge it is not possible to interact with even the simplest application) However, numbers alone do not determine an applicationís complexity. In fact, as we will see later, a small application with just a few elements can raise questions. Nonetheless, numbers can be a good indicator that an application may be hard to understand. At face value, high numbers just mean more work, not necessarily greater conceptual complexity. Yet, generally, the bigger the application, the more likely it is to include difficult concepts, and the more likely users are to encounter problems. Thus, numbers are at least an indirect measure of the need for help.

Lack of Specific Knowledge

As input fields are the most important ingredient in business applications, let's focus on these for the following discussion. To sum up, the difficulty of using a business application does not primarily result from the number of fields. Instead, it results from the specific fields in question and from the users' lack of understanding of these fields. Users may lack knowledge about:

  • The meaning of fields
  • Possible entry values
  • Alternatives to and consequences of inputs (requires decisions)
  • Dependencies between fields
  • How to proceed to achieve a goal

Meaning of Fields

Users often have no problems understanding many fields in a form and will probably never consult the online or off-line documentation for these fields. There can be, however, fields that are unclear, the input values of which are critical for further processing, or the values of which may have serious consequences. Such fields require – often extensive – explanations, which may also include their relationship to other fields in the form. In SAP R/3, F1 or field help offers information on the meaning of fields.

Input Values

Knowing what value to enter in a field is one of my biggest problems when using business applications. Sufficient background or domain knowledge is often required to successfully proceed with a task. In SAP R/3, F4 or value help provides acceptable input values.


The problem of entering correct values gets even greater if there are dependencies between input fields. For example, the value entered into one field may restrict the range of input values for one or more subsequent fields. Users often fail to recognize such dependencies, especially if there are conflicts with preceding fields. (These should not happen if the value help has been set up correctly)

Proceeding with a Task

Graphical user interfaces give users a high degree of freedom on how to proceed with a task. For example, users are not forced to enter input values in a predefined sequence, even if the layout of a form does suggest such a sequence. (This is a "subtle" kind of guidance) Functions also can be called up at any time. In the worst case scenario this occurs in situations where not enough data have been entered, or the data is inconsistent and may lead to an error. (Developers may impose some restrictions by disabling functions under certain conditions)

Generally, there is a certain amount of uncertainty with GUI applications as to how to proceed from step to step to successfully accomplish a task. This problem is exacerbated if there are dependencies between fields.

Frequency of Use

Both complexity and lack of knowledge are subjective to some degree and can vary depending on the user. For one user, a certain application can be simple and familiar, while another user finds it complex and unknown. Generally, the frequency with which a user performs a certain task is a better indicator of the need for help than categorizing the general level of computer knowledge, such as "beginner," "intermediate," or "professional." For example, a professional user may run into severe problems when using an application that contains fields with complex meanings only once or twice a year. For this application, the professional user is a casual user and has the same need for assistance as a beginner.


An Example: The Currency Converter

Here, I present a currency converter (see figure 1) as an example of a simple application with only two input fields, where users may encounter severe interaction problems. Most of the problems arise because of ambiguities when filling the fields.

Currency Converter
Starting currency        Amount
Target currency   Amount

Figure 1: A simple currency converter (not functional)

With this application, users may convert a given amount in a certain currency into another currency. You start by selecting the starting and the target currencies in dropdown list boxes; then you enter the amount in the upper input field and click the "Calculate" button. Most users will probably follow this sequence of steps because it is suggested by the application's layout. So there is a temptation here to say, "This is simple! Users don't need help."

However, not all users behave as the application designer expects them to. For example, what happens if the user does not follow the input sequence described and enters a value into the lower input field instead of the upper? In addition, some users assume that they have to enter a value into each field in a form; they would enter then a value in both of the input fields. What will happen in this case? Does an error message appear, or is one field overwritten by the result value? If yes, which one? Will all inputs be deleted, or does one field have priority, while the second value is ignored? There are a lot of options...

Let's have a look at another scenario: I enter 5 EUR in the upper field, press the "Calculate" button and get 4,93 USD as the result in the lower field. Now I want to know how many Euros correspond to exactly 5 USD. Can I simply enter a 5 in the lower field? Do I have to delete the Euro value in the upper field before I press "Calculate?" Or do I have to change both dropdown list boxes to the opposite currencies and enter a 5 in the upper field (or leave it as it is because it's already there) and delete the value in the lower field? Or is the value also deleted if the currency is changed in the dropdown list box?

Quite a lot of questions for such a simple application! Of course, there are even more questions to consider. For example, you might wonder whether the conversion values are up-to-date. I will return to this question later.

Below, I present two approaches to making this example application more intuitive for users: (1) Reducing uncertainties by providing a simple on-screen help text, and (2) introducing some changes to the design, which make the interaction with the application less ambiguous. Lastly, I will also provide a solution for getting up-to-date conversion rates.

Help Texts May Remove Ambiguities – But Not On Their Own...

Try to formulate a simple on-screen help text for the currency converter. You will soon find that this is not possible without defining a certain behavior for the application. Thus, there is an interaction between interface design and on-screen help that may lead to useful insights and improvements of an application right away. Users, however, may not notice such design decisions at first glance and may only realize they are there after some experimentation with the application.

For this example, I define the following behavior: The user has to enter exactly one value, irrespective of the position of the field; this is the start value. If the user enters two values, an error message appears (at the on-screen help location), and both values are highlighted but not deleted.

  • On-screen help text: Enter the start amount into either field – leave the second field empty.

Based on these design decisions, the user can change the direction of the conversion fairly easily. It would even easier for the user if the second field is cleared whenever the user enters a value (otherwise the user has to clear the field manually).

Currency Converter
Starting currency        Amount
Target currency   Amount
Enter the start amount into either amount field - leave the second field empty

Figure 2: A simple currency converter with on-screen help (not functional)

I do not regard it valid to give the upper field priority if both fields are filled because such mechanisms are typically hard for users to understand.

Example of a Less Ambiguous Design

The most suggestive design idea is of course to offer only one input field ready for input – the second one is disabled. In this case, users no longer need to guess,which field they have to fill and which options they have.

With this design it is harder to change the direction of the conversion – users would have to change the settings of both dropdown list boxes. Therefore, I have added a second button to the form, which offers the option of switching the settings of both list boxes Figure 3 presents the new, less ambiguous design:

Currency Converter
Starting currency        Amount
Target currency   Amount

Figure 3: Proposal for a less ambiguous currency converter (not functional)

What errors can users encounter with this improved design? For example, they may enter no value at all and press "Calculate." In this case, an error message should appear, and the input field should be highlighted. In addition, users may select the same currency twice. This could be prevented by dynamically changing the currency lists depending on the currency value of the opposite dropdown list box. I would question, however, whether so much guidance is really helpful – some users may feel it is too constraining

Extra: Up-to-date Conversion Rates

I have already mentioned that users may be unsure about the reliability of the conversion rates. An additional button could show the rate and the date of its last update.

If the currency converter runs in an environment that is connected to the Internet, it could offer manual or automatic updates of the rates. In order to avoid making this small application unduly complex, an automatic update is preferable; the date of the update could be displayed in small print in the footer area of the application.

Currency Converter
Starting currency        Amount
Target currency   Amount
Conversion rate EUR/USD = 1.002 --- last update January 20, 2003

Figure 4: Currency converter with automatic update of conversion rates (not functional)

Even with these changes, there may still be users who have problems with this application. But I assume that it is now intuitive enough to do without an online help text. Further improvements could also be achieved by changing some of the field labels, which is an important aspect in making applications more self-explanatory.

Currency Converter
Starting currency        Start amount
Target currency   Result amount
Conversion rate EUR/USD = 1.002 --- last update January 20, 2003

Figure 5: Currency converter with automatic update of conversion rates and improved field labels (not functional)

Which of the five solutions given here will be preferred by users? That question can only be answered in a user test – that's the difference between the theory and practice of user interface design!


Final Word

We all know the saying that users do not read documentation. Up to now all attempts to get rid of documentation – apart from very simple applications – have failed. Many users even despair when visiting apparently simple Websites, as Jakob Nielsen and Jared Spool report repeatedly. Software that does not need documentation is not on the cards for many years to come. Perhaps, approaches such as narrative user interfaces may bring us closer to this goal some day. Up to then, user interface designers will have to work hard to make applications more self-explanatory. As this article demonstrates, reducing ambiguities is one possible approach in this direction.

Let me conclude with the comment of a documentation writer and usability engineer, who read this article:

People have, and will always have, problems and questions about even simple applications, and therefore eliminating documentation would be foolish. Writing is a great way to communicate, but just throwing text at a question doesn't necessarily answer it. The problem I often see is that the text itself is not usable. In addition to optimizing the application and interface, the interesting and relevant question is "How can text help users? How can texts be most usable?" Instead of just saying, "Users don't read documentation," ask "What do users read, even if they don't read much? When do they stop reading?" Many factors are involved: text length and layout, how it appears or is called up, how it relates to the rest of the screen...

So, let's see what my colleague says in a second article from her point of view and experience.


top top