A Layered Approach to Translating Online Documentation  

Localizing a large online documentation system is a significant, expensive, and ongoing project. SAP AG has adapted a layered approach to translation to help manage an online help system in 12 languages. This approach is based on an analysis of online documentation categories, and it is implemented by an analysis of the target markets. Technologies such as hypertext linking and text embedding need to be carefully controlled in order for this approach to be successful.

Elliott, Keith H. STC Proceedings (1993). Articles>Documentation>Translation>Localization

Lessons Learned from Usability Testing of the Documentation  

This presentation and demonstration will first establish the principles behind usability testing of the documentation, then show examples of lessons learned from testing both print and online documentation. Video clips of actual tests will be used to make some compelling points. The session will be especially useful to those who are interested in usability testing but haven't done it yet.

Barnum, Carol M. STC Proceedings (1998). Articles>Documentation>Usability>Testing

Let the User Write the Documentation  

Teaching non-writers how to write can be challenging, especially when they are adults using new software to do their jobs. But who knows best how to write about their jobs than the end users. Through field experiences and case studies, this paper describes methods and approaches for eflectively including the end user in the documentation process, as well as educating experienced writers who are new to the system.

Doyle, Diane J. and Janet M. Samuelson. STC Proceedings (1997). Articles>Documentation>Education>Writing

Let's Stop Writing Documentation and Start Working for the Users  

Nearly 20 years ago, the profession of technical communication began to focus on developing task-oriented documentation. Although task-oriented documentation has always been produced, particularly for consumer products, it was not the standard in the computer industry. More often, people writing about computer systems focused on the system rather than on the tasks people needed to perform. Systems-oriented documentation was the norm.

ComTech Services. Articles>Documentation>User Centered Design

Let's Stop Writing Documentation and Start Working for the Users  

Technical communication's long-time focus on task-oriented documentation has left customers with too many tasks and too much information; itï¿Âs time for a new approach. A user-centered approach reflecting a thorough understanding of users and how they engage the product is the surest route to effective documentation and training. To understand what users need, we need to get closer to them by spending time in their workplaces, watching them execute everyday tasks, and listening to them. Through this kind of ethnographic activity, we will become user experts, gaining credibility within our own organizations and our user communities.

Hackos, JoAnn T. STC Proceedings (1999). Articles>Documentation>User Centered Design

Levels of Maturity in API Documentation  

This paper proposes a set of API documentation maturity levels that can be used to define a writer or writing team’s ability to document technical materials and to set goals for moving between levels towards more independence from developers. It examines development and documentation team process maturity, as well as several types of API documentation, and their impact on writers new to producing developer documentation. The paper also discusses some of the common difficulties associated with developer-level documentation.

Kozlowski, Paula and Benjamin Dollar. STC Proceedings (2004). Articles>Documentation>Programming

Life: A User's Manual

With his back towards the reader, a bucket over his head, hands and feet tied up by SGML, CALS and company standards, and half choked by all the possibilities of the latest computer system the writer tries to produce manuals and instruction books for unsuspecting readers!

Forsslund, Lars. TC-FORUM (1998). Articles>Documentation>Writing>Technical Writing

Lightweight Literate Programming: A Documentation Practice    

Lightweight literate programming (LLP) combines software documentation and coding in a way that can scaffold collaborations between technical communicators and programmers. We review the genesis and history of LLP, including its relationship to established single-sourcing methods. We then detail its use by programmers and discuss two models for writer/programmer collaboration using LLP. We finish by suggesting a few studies of working relationships between writers and programmers that LLP could facilitate.

Stavely, Allan, Lynda Walsh and John Shipman. Technical Communication Online (2008). Articles>Documentation>Programming>Methods

Linking Context-Sensitive HTML Help

The mechanism that Doc-To-Help uses for mapping topics in a context-sensitive HTML Help differs from the mechanism it uses for context-sensitive WinHelp. This article tells you what you need to know to properly link context-sensitive HTML Help to an application.

ComponentOne (1999). Articles>Documentation>Online>HTML

Listening: the Often Forgotten Ingredient

If listening isn't in the mix when developing documentation, then the project may not cook.

Allen, Clare. Boston Broadside (1992). Articles>Documentation>Collaboration>SMEs

Little Machines: Understanding Users Understanding Interfaces    

This paper questions the ubiquitous practice of supplying minimalist information to users, of making that information functional only, of assuming that the Shannon-Weaver communication model should govern online systems, and of ignoring the social implications of such a stance. Help systems that provide fast, temporary solutions without providing any background information lead to the danger of users completing tasks that they do not understand at all. (Word will help us write a legal pleading, even if we have no idea what one is.) As a result, we have help systems that attempt to be invisible and to provide tool instruction but not conceptual instruction. Such a system presents itself as a neutral tool, but it is actually an incomplete environment, denying both the complexity and alternative (and possibly improved) modes of thinking about the subject at hand.

Johnson-Eilola, Johndan. Journal of Computer Documentation (2001). Articles>Documentation>User Centered Design>Usability

Living Documentation: The Future of Technical Writing

Living documentation is documentation that does not cease to be developed until the product ceases to develop. Living documentation can be produced at any time in multiple formats. The book, web pages and online help would continue to be developed as long as that development either solves inaccuracy or increases product usability and customer satisfaction.

Hewitt, John. Writer's Resource Center. Articles>Publishing>Documentation>Online

The Logical and Rhetorical Construction of Procedural Discourse     

A very useful perspective for understanding procedural ('how to') discourse and for writing better procedures is to view procedures as a framework of actions and states. The states include desired (goal) states and unwanted states; the actions are user actions, system actions, and external events. This framework underlies all kinds of procedural discourse, including streamlined-step procedures, the model that predominates in online help systems. The components that make up streamlinedstep procedures are best understood as combinations of actions and states. Procedural discourse is also highly rhetorical in nature. We can see the rhetorical implications of actions and states in the various models of procedural discourse, and in specific strategies that writers implement. Because of its terse and rigid nature, the streamlinedstep model is not well suited for certain rhetorical strategies and cognitive goals, and so while recognizing the efficiency of the streamlined-step model, writers should not neglect more

Farkas, David K. Technical Communication Online (1999). Articles>Documentation>Rhetoric

Lovely DITA, DocBook Fades?  

Makes the case for DITA and provides a compare-and-contrast of DITA and DocBook.

Dumbill, Edd. Intercom (2006). Articles>Documentation>Standards>DITA

Maintaining Documentation Across Several Languages  

As more companies move into markets beyond their borders, many technical communicators are faced with this new situation of having to deal with more than one language for their documentation The costs and time involved in localising and maintaining these documents can be substantial. This paper briefly discusses some of our experiences and gives some pointers on how a technical communicator can ensure the successful maintenance of documentation across several languages.

Pereira, Reynold G. and Jennifer O'Neill. STC Proceedings (2003). Articles>Documentation>Localization

Maintaining Quality Control in Documentation  

If all of us were more focused towards quality in our lives, we would have it in abundance. We would have higher satisfaction levels and therefore, have lesser complaints. This paper presents cases and reasons why user manuals and guides are not up to the expected standards. Do we need to go beyond checklists before shipping a document? Are reviews and checklists sufficient? This paper briefly talks about the measures that we could take to ensure that a good document is delivered.

Singh, Neelam. STC Proceedings (2002). Articles>Documentation>Assessment

Making Documentation Accessible to Users With Disabilities  

Good documentation takes into account the needs of people with disabilities. Such documentation is termed 'accessible' and provides support for the assistive technologies used by people with disabilities. For example, accessible documentation provides a text equivalent for each graphic element, such as a picture, flow diagram, or icon. This provision is necessary for users who rely on screen readers to read the documentation.

Chappell, Gail B. STC Proceedings (2003). Articles>Documentation>Accessibility>Technical Writing

Making Help More Human, and Other Discussions

Discusses a number of trends in the technical writing world, particularly the need to make help more human by adopting conversational tones and addressing the angry/frantic state of the user.

Johnson, Tom H. and Heidi Hansen. Tech Writer Voices (2007). Articles>Documentation>User Centered Design>Help

Making Online Help Helpful -- Perspectives of Professionals and Users  

This paper reviews research done in online help information, analyses different views on it from the perspectives of professionals of technical communication and end-users, and suggests ways to solve problems.

Li, Yue. STC Proceedings (2003). Articles>Documentation>Online>Help

Making Online Information Usable

So you follow all the standards and guidelines, but suffer nagging questions about whether anyone can and will use the help you’ve just written. Or management wants you to move your printed documentation online, but you wonder whether that’s really best for your users. In the course of our consulting work, we’ve done dozens of usability studies that focus on how people use a variety of printed and online documentation, including manuals, help, cue-cards, and wizards. We’d like to share some of our results and observations, in hopes that this will help you make more informed design decisions.

User Interface Engineering. Articles>Usability>Documentation

Making Product Information an Integral Part of the Development Process  

Document inspections formalize the document review process and encourage the full participation of technical developers in the documentation development process. A document inspection consists of three parts: a briefing meeting, a desk review, and a recording meeting. At the briefing meeting, you state your requirements for the inspection process. During the desk review, the technical developers review your document. At the recording meeting, you review the comments made by the technical developers, and as a group decide on appropriate resolutions.

Hildebrand-Lund, Ruth. STC Proceedings (1996). Articles>Documentation>Workflow>Technical Writing

Making Sense of Step-by-Step Procedures    

Procedural instructions that consist of only a sequence of steps will probably be executable, but nevertheless 'meaningless' to users of technical devices. This paper discusses three features that can make procedural instructions more meaningful: adding functional coordinating information, adding information about the use of the technical device in real life, and adding operational information about how the device works. The research literature supports the effectiveness of the first feature, but offers little evidence that real life elements enhance understanding of instructions. As for operational information, the research suggests that users are willing to read it, and that it contributes to better understanding and performance in the long term, but only if it is closely related to the procedure. As a conclusion, we propose a theoretical framework that assumes three levels of mental representation of instructions: syntactical, semantic, and situational.

Steehouder, Michael F., Joyce Karreman and Nicole Ummelen. ACM SIGDOC (2000). Articles>Documentation>Rhetoric>Technical Writing

Making Web-Based Online Help Accessible: A Case Study  

Accessibility is about providing successful access to information, and the use of information technology by people who have disabilities. The IBM® WebSphere® Commerce development team adopted IBM’s mandate to make its software accessible, and achieved a high level of accessibility in its release of the IBM WebSphere Commerce, Version 5.4, suite of products. Continuing with the next release, the WebSphere Commerce development team strove for an even higher level of accessibility. This paper discusses some of the experiences and lessons learned from making WebSphere Commerce online help and software accessible. It examines some of the most common issues from the User Experience, Information Development, and Test perspectives.

Bot-Roche, Diba, Frances Mullally, Vijay Sivashankar and Donna Sutarno. STC Proceedings (2003). Articles>Documentation>Accessibility>Help

Man, Machine and Technical Communication

Producing technical documentation is a wide-ranging process. It varies from company to company and from project to project. Often we are dealing with an extensive, multilingual project, which is going on simultaneously in many countries. Documentation must be consistent and systematically produced and updated: it works as a base for multilingual user documents from installation guides to marketing material. Documentation takes into consideration the language and cultural differences of various target groups as well as differences in information perception and learning. Forms of communication also vary: part of it is in traditional paper format, but electronic formats and multimedia are being used more and more.

Varantola, Krista. University of Tampere (1999). (Finnish) Articles>Documentation