Writing Patterns: Improving the Help Experience

Dana Spradley, Principal Software Engineer
Ultan Ó Broin, Director, User Experience

Dana Spradley

Ultan Ó Broin

As our colleague George Hackman noted in his recent blog entry Design Patterns for User Experience, Oracle has developed over 100 user interface design patterns that outline the best high-level solutions to common user interface (UI) design problems. This enables Oracle application developers to quickly and consistently put together quality UIs that make the user experience much more pleasant and productive.

At Oracle we've also begun to develop design patterns for something they've never been applied to before: online help. Buildings have a physical structure, UIs a visual and experiential one. Help topics have a structure too--the concrete way in which they present and organize ideas. They're much easier for users to understand and learn from if the structure follows a few good design principles in the first place. The writing patterns we've developed at Oracle provide high-level guidance to our technical writers on the best way to design, organize, and write each of the various kinds of help topics we've identified. Design patterns are widely used by user experience professionals (Van Duyne et al, 2006) and there are many examples available publicly (Tidwell, 2005; Yahoo! Design Pattern Library), so why not bring the technique to technical writing?

So far, we have created 16 writing patterns. They cover a variety of frequently asked questions ("Why did...?," "What happens if...?," "How can I...?," situations, and so on), conceptual information topics (such as applications architecture, information processing, decision support), examples (simple examples, conceptual examples, step-by-step case solutions), and glossary items.

The patterns are designed with the user in mind. The resulting help topics integrate with the intuitive productivity-enhancing features of the UI itself and any other user assistance (for example, messages or embedded UI help.) Writing patterns make it easier for technical writers to avoid developing overlapping, redundant, or irrelevant information, for which no patterns are provided, and concentrate instead on creating essential, well-written topics that more closely meet users' needs.

This innovative design approach means technical writers have tools at hand that go much further than traditional sources such as the Chicago Manual of Style (2003), which deals more with guidance at the level of grammar, style, and word usage than with meeting targeted business requirements for information provision. For example, our writing patterns have been developed to meet the needs of users searching for (BBC, 2008) and reading information online (Nielsen, 1997, 2006), among other requirements.

Sample Writing Pattern

As an example, let's look at the frequently asked question (FAQ) "What's the difference...?" writing pattern. It states up front that users need to understand the differences between similar or related application concepts or terms so that they can make an informed decision before making a choice on how to proceed (for example, the difference between Demand Planning and Supply Planning). The solution is to write a help topic using this pattern.

The pattern details how to compose a help topic meet the users' need for information, through a series of steps illustrated by the following rough diagram of the topic's structure:

Figure 1. Pattern diagram showing the structure of a "What's the difference...?" FAQ help topic.

The topic structure (figure 1) starts with a title (the userQuestion part) that uses a suggested phrasing for the question being asked ("What's the difference between and ?"). A mainDifference section that explains the first term in a point paragraph, and the second term in a counterpoint paragraph, answering the question, follows. If there are more distinctions to be made between the terms, then the pattern provides for an otherDifference section, allowing the writer to make other points and counterpoints. If the terms are actually synonyms, then a noDifference section can be used instead.

As in the case of Oracle's UI design patterns, the key components of Christopher Alexander's (1977) original architectural patterns (problem, context, and solution) also ring true for help topic writing patterns. Technical writers need to know the users' roles and how they actually work with the software to pick the best writing pattern for the job. And as in the case of UI design patterns, we've provided writers with a decision support tool to aid them in choosing just the right writing pattern, and review a cross-section of each writer's work to provide feedback about the pattern they've chosen and why, informing pattern development or training needs.

From Pattern to Schema

Each writing pattern is developed until it encapsulates our current best hypothesis about the optimal way to structure a help topic to solve a particular usability problem. We then translate that structure into a Darwin Information Typing Architecture (DITA) XML schema that, integrated into our XML authoring tool, directly prompts the technical writer to use specific content-based elements at each stage of the composition process. This maximizes writer productivity and further ensures consistent results. Each schema is, technically, our own specialization of an existing DITA schema, allowing much of the HTML output processing already developed generically to automatically apply to our pattern.

The real advantages of the writing pattern approach are for the users of our documentation: a consistent user experience, easier learning, faster transfer of information, and an ease of use of topics accessed through search and read online.

We'll take a look at some more writing patterns and discuss their validation through testing in future postings on usableapps. For now, we welcome your comments below.


  • Alexander C. 1977. A Pattern Language: Towns, Buildings, Construction (Center for Environmental Structure Series). Oxford.

  • BBC News 2008. Web users getting more ruthless. Online. Available from http://news.bbc.co.uk/1/hi/technology/7417496.stm [Retrieved 16-July-2009]

  • Nielsen J. 1997. How Users Read On the Web. Online Available from http://www.useit.com/alertbox/9710a.html [Retrieved 16-July-2009]

  • Nielsen J. 2006. F-Shaped Pattern For Reading Web Content. http://www.useit.com/alertbox/reading_pattern.html [Retrieved 16-July-2009]

  • The Chicago Manual of Style. 2003. University of Chicago Press

  • Van Duyne D K, Landay J A, Hong J I. 2006. The Design of Sites: Patterns for Creating Winning Web Sites. Prentice Hall.

  • Tidwell, J. 2005 Designing Interfaces: Patterns for Effective Interaction Design. O'Reilly.


Post a Comment:
  • HTML Syntax: NOT allowed

The Oracle Applications User Experience (OAUX) Usable Apps in the Cloud blog.

Oracle Applictions User Experience logo

Twitter Usable Apps on Twitter

Main OAUX Website:

Usable Apps