Design: User Assistance Design

Simplified Technical English (STE) and minimalism are of great importance in writing user-friendly documentation, particularly for user content such as maintenance manuals. However, many technical writers experience specific problems when implementing STE and minimalism. The ASD-STE100 Specification is a complex document, and a disadvantage of this approach is its expensive learning time. Plus, literature about minimalism comprises complex documents, and training is scarce.

In this article, we’ll clearly describe the steps you need to take to implement the principles of Simplified Technical English and minimalism in designing optimized, user-friendly documentation. First, we’ll cover the concepts behind the Thumbs-Up Technique—principally, STE and minimalism. Next, we’ll detail the steps to follow in implementing STE. Finally, we’ll detail the steps to follow in implementing minimalism. By following the steps we’ll outline, you can apply the principles of STE and minimalism to your documentation quite easily. Read More

In this column, instead of talking about one of my usual topics—tactics to avoid errors—I’ll discuss how to work within constraints and pragmatically address real-world issues. During the software-development process, your team may ask you to design an error message. Annoying edge cases all too often pop up—usually too late in the process to fix the issue in any other way.

For starters, I never write what I’d call error messages. Admittedly, I occasionally use that term—in the same way I might use words such as sitemap—just at the beginning of a conversation to orient everyone to my process. Just as I did in the title of this column. But I then switch to a more meaningful term and get everyone to talk about exception messages. Read More

Tables get a bad rap—especially in the Web world where, once upon a time, Web developers misused them for HTML layout. But tables are still very useful for the purpose for which they were originally intended—a way to show relationships among discrete data points. From a user assistance perspective, we deal with tables in two contexts:

1. user assistance—Tables can present information or instructions in our documentation.
2. user interfaces—Tables can display information within a user interface itself.

In this column, I’ll review some of the basic principles of good table design from an information developer’s perspective, then discuss their visual design and interactivity. These principles and my examples provide the bare essentials of table design. When designing tables, a key information design objective is keeping them simple, so if you start needing more than this column provides, you might be making things unnecessarily complicated for your users. Read More