Building Documentation into the Interface  

As documentation is more and more built directly into the interface, and as technical communicators move into interface design and usability, it is important to have a theoretical framework within which to make decisions about what kind of information will be conveyed at any moment. We can build on basic principles of cognitive psychology to help us make these decisions. We start from a question: Why should users be aware of the difference between interface and documentation when all they want is to get something done?

Quesenbery, Whitney. STC Proceedings (1998). Articles>Documentation>User Interface>Help

Building Documentation Into the Interface: A Cognitive Theory  

As documentation is more and more built directly into the interface, and as technical communicators move into areas of interface design and usability, it is important to have a theoretical framework within which to make decisions about what kind of information should be conveyed at any moment.

Quesenbery, Whitney. STC Proceedings (1997). Articles>Documentation>User Interface>Cognitive Psychology

Context-Sensitive Help: What Programmers and Technical Authors Need to Know

Context-sensitive Help is assistance that is appropriate to where the user is in the software application, and what they are trying to do. Carol Johnston's article describes what programmers and technical authors need to know about Context-sensitive Help.

Johnston, Carol. Cherryleaf (2003). Articles>User Interface>Help>Documentation

Does a Good User Interface Obviate the Need for Documentation?

This question was raised on a programmer's group recently and I was intrigued. The programmer's point was that with many web applications these days there is no print documentation distributed to end users, and even if it existed, many users won't read it although this makes me wonder who's buying all those how-to books I see in the bookstore. The programmer suggested that applications should be designed without documentation and wondered about the impact that would have on design.

Sprezzatura Systems (2002). Articles>Documentation>User Interface>Software

How Design Documents Enhance Information Product Development Process Quality  

Panelists from LSI Logic Storage Systems review their company's approach to enhancing process quality by using design documents as process enforcement and project-planning tools for planning the development of information products (IP). Hear how effective planning solves problems that occur during the IP development process and how capturing the planning elements in design documents helps solve role-based problems for developers, editors, and managers. Discuss the many problems design documents help project teams solve: they help developers solidify the IP development task sequence, they help editors define the rhetorical context, and they help managers reduce the cost of rework.

Burroughs, Dia H., Randy Clark, Sylvia McCombs and Tony Washington. STC Proceedings (2004). Articles>Documentation>User Interface>Workflow

Instructive Interaction: Making Innovative Interfaces Self-Teaching  

An innovative approach to enhancing ease of use and learning for novel user interfaces is described. Instructive interaction comprises a body of techniques based on a learning-by-doing model that is supported by three design principles: explorability, predictability, and guidance. Taken together, these principles form the basis for creative designs that can support highly efficient production use by experienced users while also enabling new users to understand and make effective use of an unfamiliar system almost immediately. The underlying principles of instructive interaction are presented here and an assortment of specific techniques based on these principles is described.

Constantine, Larry L. and Lucy A.D. Lockwood. Constantine and Lockwood (2002). Articles>User Interface>Documentation

New Life for Product Documentation

Here are some 'truths' we've all heard: 'Documentation is just a band-aid for poor design.' 'Real users don't read manuals.' 'Super users never read anything.' 'Help doesn't.' But are they really true? I've seen some signs of life in the use of documentation for digital products recently.

Quesenbery, Whitney. UXmatters (2006). Articles>Documentation>User Interface>User Centered Design

Task Based Documentation and Good User Interface Go Hand in Hand

As I write the 'how to' documentation based upon the in-process design, the weaknesses of my original design become apparent and I go back and forth from writing text to designing the software until it all flows.

Ferlazzo, Ellen Lawson. Sprezzatura Systems (2002). Articles>Documentation>User Interface>Usability

How to Improve the UI--Really!

A colleague has made me realize that user assistance writers are codependents of bad UI design. Because we explain how the UI really works, we somehow leave our developers and companies feeling like they're "covered" when the users have a bad experience.

Hughes, Michael A. User Assistance (2009). Articles>User Interface>Documentation>Technical Writing

User Interface Pattern Documentation Review

User interface (UI) patterns have the potential to make software development more efficient. The prospect of such efficiency gains has led to interest in user interface (UI) patterns by individuals and organizations looking for ways to increase quality while at the same time reducing the costs associated with software development.

Stapleton, Patrick. Boxes and Arrows (2009). Articles>User Interface>Documentation>Functional Specifications