I Know What You Need to Know: Is that User Centered Documentation?

Quality management is forcing technical communicators to meet the challenge of writing user-centered documentation. Adequate preparatory work would be to categorize potential users according to experience, knowledge, tasks to be performed, and other use-relevant features. Users' requirements and requests should then be incorporated into the document's design.

Bock, Gabriele. TC-FORUM (1999). Articles>Documentation>User Centered Design

IBM User-Centered Design for the Documentation Designer  

The user-centered design of documentation is an aspect of product design that has often been under-emphasized. Difficulties inherent in documentation design include obtaining user, feedback to high-level design objectives; extracting user. feedback specific to a product’s documentation. rather than to the product as a whole; and managing the various resource constraints inherent in product development. IBM User-Centered Design offers a solution to these difficulties by employing a set of user feedback methodologies from which the documentation designer, a member of a multidisciplinary design team, extracts pertinent data to set design objectives and follow through to low-level designs.

Righi, Carol and Lynn VanDyke. STC Proceedings (1996). Articles>User Centered Design>Documentation>Technical Writing

Ideas on Cooperation Between Suppliers and Users Regarding Documentation

Documentation, operators’ manuals, maintenance instructions, etc, can never be perfect and satisfy all users. The organization of the documentation, particularly for large systems, will never suit all users and there will always be some errors present. This means the supplier and the user need to cooperate in various ways to avoid the fatal consequences of errors and misinterpretations, and for the improvement of documentation over time.

Rullgård, Åke. TC-FORUM (2001). Articles>Documentation>User Centered Design

Improving Document Quality Through Customer Visits  

In an effort to improve the quality of our documentation, our Information Development department personally visited over 80 of our customers in 10 different locations across the United States. Our goal was to find out what we needed to do to create documentation that would satisfy our customers' needs. We came up with a process for planning our visits, gathering the information from our customers, implementing their requirements, and increasing communication with them. From the visits, we not only made changes that immediately satisfied our customers, but we created an environment for them to work with us as a team.

Lass, Laura W. and Wendy L. Reed. STC Proceedings (1993). Articles>Documentation>Quality>User Centered Design

Improving Documentation Through Customer Feedback: A Case Study  

By soliciting and receiving customer feedback, writers learn how customers use existing documentation and what additional information customers may need. In May 2001, we began a formal process of gathering customer feedback for the IBM WebSphere Commerce Suite product. The first phase of this process involved two main initiatives: creating and promoting a documentation questionnaire for customers; creating and working with an internal test team that acted as customers. Feedback allowed us to determine which information strategies helped customers meet their business needs, and which areas we need to concentrate on in future releases.

Heximer, Erin and Lisa Wu. STC Proceedings (2002). Articles>Documentation>User Centered Design

Improving Documentation with Learning Techniques  

It is important to recognize that because we all differ in our experience and background the learning process is different for each of us. Consequently, in our documentation we should by to put users on an equal footing by, for example, clearly and exactly defining terms we use and including a glossary. We can also put everyone on an equal footing by using 'bridges to understanding,' from analogies, examples, and metaphors to mnemonic strategies. For overall comprehension, we can employ 'frameworks,' from conceptual maps to road maps, that give patterns of meaning to what we say.

Livingston, Dick. STC Proceedings (1993). Articles>Documentation>Instructional Design>Glossary

Increasing User Acceptance Of Technical Information in Cross-Cultural Communication    

A significant problem in technical communication is persuading the user that the information is accurate, valid, and useful. All too often, technical communicators treat users as members of their own culture. When authors do consider cultural issues, they often focus on matters such as vocabulary, visuals, and organization. Other strategies, however, can be useful in gaining acceptance of technical information in cross-cultural situations. For example, the communication theory of compliance-gaining offers suggestions for how the technical communicators can adapt the text to enhance user acceptance when communicating to members of their own culture as well as when communicating across cultures. Communicators can use promises, threats, demonstrate positive and negative outcomes, extend friendliness, etc., to develop the text. In this article, I will explain several compliance-gaining strategies authors can use, identify rhetorical strategies they can combine with compliance-gaining strategies, show how these strategies can be effective in a cross-cultural environment by comparing the strategies in two sample cultures, and analyze a brief sample.

Warren, Thomas L. Journal of Technical Writing and Communication (2004). Articles>Documentation>User Centered Design>International

An Information Make-Over for Performance Centered Design  

Technical communicators have long harbored a secret that we are reluctant to admit to outsiders: Users don’t like reading manuals. They do it only as a last resort. Even online help systems, which we originally hoped would be easier to use, have not met with great enthusiasm among users. It’s an all-too-common dilemma – there is a lot of information that could be explained, but users struggle along as best they can without it. Part of the problem has always been that users are reluctant to leave their work to seek information -- and rightly so. They have work to do and deadlines to meet. Even if your manual or online help contains a wealth of useful information, it takes them away from their work and interrupts their train of thought. If they do try to use it, the help window typically overlays the interface and adds its own set of navigation, resizing, and searching issues.

Battle, Lisa H. STC Proceedings (2000). Presentations>Documentation>Information Design

Information Planning for Successful Online Documentation  

Creating an information plan should be the first phase of any publication development life cycle, whether hard copy or online. The plan is a tool for reporting the results of your research about your audience, their tasks, the market, and the product. The plan presents the basic organization and content of the publications you intend to build, effectively directing the documentation team to produce a publication with very specific goals in mind.

Stevens, Dawn M. STC Proceedings (1996). Articles>Information Design>Management>Documentation

Instruction-Writing Exercises (for High School)

These guidelines and 14 scaffolded exercises respond to the unmet need for a psychologically solid, work-relevant way to learn technical writing by students who are NOT facile writers already.

Girill, T.R. STC East Bay (2001). Articles>Education>Instructional Design>Documentation

Instructional Design and Software Quality Assurance, Part I  

Describes how instructional design principles can improve documentation.

Nayar, Pawan. Intercom (2001). Articles>Documentation>Instructional Design

Instructional Design: Choosing the Proper Authoring Tool  

Searching for the right tool for your instructional design needs? Learn about your options through capsule reviews of instructional simulation programs and full-service authoring tools.

Holden, Gene. Intercom (2004). Articles>Documentation>Instructional Design

Intentional Learning in an Intentional World: Audience Analysis and Instructional System Design for Successful Learning and Performance    

How do we support successful, lifelong learners and performers and help them competently respond to rapidly changing opportunities in the 21st century. The answer to this question lies in how well we understand audiences differentiated by key learning differences and consider how these differentiations influence winning learning and performance. Historically, cognitive-rich explanations have tended to underplay the dominant impact of affective and conative factors on thinking and learning. Recently, these dimensions have gained considerable importance as contemporary multidisciplinary research has begun to demonstrate how intentions and emotions can influence, guide, and, at times, override our thinking and other cognitive processes. More importantly, research suggests that intentions and emotions are a dominant, powerful influence on learner success.

Martinez, Margaret. Journal of Computer Documentation (2000). Articles>Documentation>Instructional Design>Education

Interactive Help: Adapting Content for Multiple Users  

Most online help systems present a 'one-size-fits-all' solution—fixed content for each topic—but users’ experience levels and backgrounds are complex and diverse. Users lose time and patience sifting through topics that either do not match the problem a user is trying to solve, or that present information that does not match a user's knowledge level. A group of Masters students at Carnegie Mellon University tackled this problem. As a course project, the team created an online help prototype that contains different levels of help, a prototype that gives users a choice about how much information they want to see.

Downs, Christina M. and Anne F. Jackson. STC Proceedings (2001). Design>Documentation>Online>Help

Introduction of Programming Technology for Improving Manual Production  

How do we introduce programming technology successfully and illustrate various applications using SGML, Visual Basic, RTF, HTML and other tools which drastically change the manual production process? The following is an explanation of how we at Seishosha Co., Ltd. have dealt with this matter.

Kobayashi, Norio. STC Proceedings (1995). Design>Documentation>Programming

An Introduction to Embedded Assistance  

Everyone hates help, right? Why? Help is inherently reactive, anticipating users' failure rather than providing information when users need it--before they fail. Print documentation, further from the user’s task at hand, is even more guilty of these sins. This paper presents an overview of embedded assistance, describing the current help paradigm and why it's failing and the basics of embedded assistance, as well as the technologies and infrastructure and the skills and knowledge you need to develop effective embedded assistance.

Ames, Andrea L. STC Proceedings (2002). Design>Documentation>Help>Embedded

Is Your Website Poised to Deal With Its Growth?  

Every webmaster nourishes the dream that his or her website will make it the big way. This is very much human because people carry out any task in ardent hope. What is more human out here is that earthy fellows like us base our aspirations more on speculation rather than specific set of steps undertaken to bring the dream a bit closer to reality. And this is not all, particularly in case of growth of a site which brings newer problems in the wake of its growth. It cannot be disputed that you can probably get some good web hosting on economy price. But if you expect top of the line service on this price, acknowedge gracefully that your are just asking for the moon. Probably you are not catching up with wisdom that business needs decisive investments.

Azam, Rahbre. Amateur Writerz (2008). Articles>Documentation>Web Design>Technical Writing

It's Not Enough to Say What it Does

All too often, developers think that documenting their new creations just means writing a detailed technical description of what it does. In a sense, they're explaining things to themselves. But what you really need to do is explain things to someone who's coming across your stuff for the first time.

McManus, Eamonn. Artima (2004). Articles>Documentation>User Centered Design

John Carroll's The Nurnberg Funnel and Minimalist Documentation    

A review of the use of minimalist theory in the creation of documentation sets.

Farkas, David K. and Thomas R. Williams. IEEE Transactions on Professional Communication (1990). Design>Documentation

Just Say "Help": Implementing Help in VoiceXML

One of the exciting aspects of XML is the number of ways it is being used to provide new means of communicating and gathering new information. One such use is VoiceXML, an emerging W3C standard that brings voice to the Web or the Web to the phone.

Beebe, Allen. WritersUA (2002). Design>Documentation>XML

Keeping Pace with Change

Documentation isn't the most fun part of design and IA, but does it have to be the most painful? Samantha Bailey looks at a tool that may help.

Bailey, Samantha. Boxes and Arrows. Articles>Documentation>Information Design

The Kind of Documentation Users Really Want

Have you ever asked your users what kind of training materials they want, or how they prefer to learn software? This kind of information is critical to figuring out what help deliverables to produce. But really when it comes down to it, there are only so many options — printed manuals, short guides, interactive flash guides, videos, online help, live training, reference cards, context-sensitive help, workbooks and exercises, or, usually the favorite, someone to stand by their computer and answer questions whenever they need help.

Johnson, Tom H. I'd Rather Be Writing (2008). Articles>Documentation>Usability>User Centered Design

Large-Scale HTML Conversion Using a Word Processor  

In 2000, the Hitachi Technical Information Department carried out a large-scale documentation project requiring the revision of 47 English manuals (about 15,000 pages) and production of the manuals in both paper and HTML formats. Many projects of this size would normally use more complex software and file formats, such as FrameMaker and SGML. However, most of the English manuals were already in Microsoft Word (hence forth 'Word') format, and we decided to use Word 2000 to convert the manual document files into HTML files directly. The presentation discusses solutions to problems encountered in this HTML conversion project.

Hara, Takayoshi and Mayumi Seitou. STC Proceedings (2001). Design>Documentation>Web Design

The Leap Online  

McGowan discusses how documentation departments can ease the transition from a paper-centered work environment to an online one.

McGowan, Kevin S. Intercom (2000). Design>Documentation>Online