Getting to Expert

The gaps in your documentation aren’t there because you haven’t consider a particular level of user; the gaps in your documentation are there because you haven’t considered how one level of user becomes another. How DO you get from Beginner to Expert?

McLean, Gordon. One Man Writes (2008). Articles>Documentation>User Centered Design>Technical Writing

Give Them Printed Documentation, Too!!!

The current trend among technical communicators is a twisted form of minimalism that says the documentation should contain procedural documentation but little or no reference documentation. I believe that this trend is a disservice to our customers and tends to increase technical support costs because customers subjected to this form of documentation have little or no access to the information they need. If it’s not there, they can't find it.

Starr, Mike. TC-FORUM (2002). Articles>Documentation>User Centered Design

Goal-Oriented Paper Versus Online Documentation Search Strategies  

In this age of information, advanced technology gives us access to more than ever imagined. Are people easily moving toward gathering information online instead of from paper? This study investigated novice and expert user access of paper versus online documentation.

Anson, Patricia H. and Robert Anson. STC Proceedings (1996). Articles>Documentation>Online

Going Global Without Going Broke  

Companies are increasingly operating world wide. As a result they often need to produce documentation in several languages to meet market demands. The quality of the source document plays an important part in controlling the cost and release date of the localised documents. This article discusses several issues that need to be considered when producing documents for the multilingual marketplace.

O'Neill, Jennifer. STC Proceedings (2001). Articles>Documentation>International

Going Online: A Case Study in the Development and Implementation of Netscape NetHelp  

Computerized Medical Systems, Inc. (CMS) - the worldâ*™s leading radiation therapy planning (RTP) company with over 1000 installed RTP systems and over 400 installed dosimetry systems - decided in late 1996 to move existing FOCUS documentation online. Reasons for this included: the existing documentation set perceived as too difficult to use; increasing printing cost; and customer feedback. Using Netscape NetHelp as a basis, the CMS documentation staff reduced printed documentation size by two-thirds while making the information more accessible. Reactions to FOCUSHelp have been highly favorable. Future plans include migrating to the NetHelp2 framework and reducing topic lengths.

Rupel, Roberta A., Ellard Douglas, Bill Bledsoe and Frank Watson. STC Proceedings (1998). Articles>Content Management>Documentation>Help

Going Online: Selecting the Right Tool  

There are numerous tools that you can use to create online documentation. However, each tool has its strengths and weaknesses, and each is more appropriate for some types of information than others. This workshop explores many issues of online documentation tools: Why go beyond Windows Help? Which is better: HTML or Adobe Acrobat? What tools support cross-platform presentation? When should you use Workgroup tools such as Lotus Notes or Folio? When does SGML make sense? How to utilize a!ocument databases? When to use Management tools? Real examples developed using these tools will be given throughout the session. Participants will leave with a clear understanding of the pros and cons of each.

Rockley, Ann. STC Proceedings (1997). Articles>Documentation>Software>Help

Going Paperless — No Longer a Revolutionary Idea  

Moving user documentation from paper to online requires long–term planning and hard work. You must rethink how you design documents and determine the best way to present information online. You can take steps to downsize the existing documentation workload. You may even change the way you work with the software development staff. As a result, you will probably produce better documents, start working a lot smarter and save the company a lot of money.

Mulreany, Sharon R. and Risa Glick. STC Proceedings (1996). Articles>Documentation>Online

Grappling with Distributed Usability: A Cultural-Historical Examination of Documentation Genres Over Four Decades    

Traditional models of usability assume that usability is a quality that can be designed into a particular artifact. Yet constructivist theory implies that usability cannot be located in a single artifact; rather, it must be conceived as a quality of the entire activity in which the artifact is used. This article describes a distributed approach to usability, based on activity theory and genre theory. It then illustrates the approach with a four-decade examination of a traffic accident location and analysis system (ALAS). Using the theoretical framework of genre ecologies, the article demonstrates how usability is distributed across the many official and unofficial (ad hoc) genres employed by ALAS users.

Spinuzzi, Clay. Journal of Technical Writing and Communication (2001). Articles>Documentation>Usability>History

Grassroots Documentation  

We often hear how the Web can be used to deliver technical documentation. But have you ever thought about the Web as technical documentation? When dozens, or perhaps hundreds, of people, all using the same product, start posting tips and solutions to problems on different Web sites, the entire Internet becomes a kind of crude users’ manual.

Martin, Maurice. Intercom (2003). Articles>Documentation>Online>Community

A Guide for Software Project Managers - Planning User Documentation

A Guide to the Project Management Body of Knowledge (PMBOK® Guide)–2000 Edition is the main sourcebook in the project management field. Whilst it covers Project Communications Management, it doesn't extend to user documentation. This article seeks to provide guidance for project managers as to how the user documentation process fits in with the overall project planning. It examines: the traditional way documentation is approached and how it impinges on project planning the effects of making changes to this traditional approach.

Johnston, Carol. Cherryleaf (2003). Articles>Documentation>Project Management>Body of Knowledge

Guidelines for Writing Technical Documentation for an International Audience  

A guide to help technical writers in all countries who have to write English-language technical documentation for products that will be sold worldwide.

tekom (2003). Articles>Documentation>International>Technical Writing

Harnessing the Earthquake: Reaching Group Consensus When Changing the Documentation Process  

A causal-analysis session is a problem-solving method that brings groups of people together to jointly solve common problems and make process changes. This method ensures that everyone who will be affected by a process change has the opportunity to provide input and agree to the solution. In large departments, reaching group consensus is a challenge. This paper presents our department's implementation of the causal-analysis method.

Coppola, Carolyn M. and Kristine Logan. STC Proceedings (1994). Articles>Documentation>Collaboration

Harry Miller on Multimedia Documentation

Miller, a technical editor at Microsoft interested in multimedia documentation, talks about why multimedia documentation is a growing trend and how writers can get started. He discusses Microsoft's Channel 9 and the human element with instructional screen demos.

Miller, Harry and Tom H. Johnson. Tech Writer Voices (2007). Articles>Interviews>Documentation>Multimedia

Help Development: "Just in Time, and Just Enough"

Too often technical writers fall into the 'tell them everything and tell them all at once' pit. Guided by a well-meaning desire to 'educate' users, what these writers typically do is overwhelm them. Finding the information you need when you need it is a key to success in every business function of every company. Therefore, technical communicators who are able to provide their customers with quick and useful knowledge bring an incredible added value to a beleaguered work force constantly expected to do more and to do it faster.

Edwards, Verlane. STC Central Iowa (2000). Articles>Documentation>Online

Help Is Dead. Long Live Help!  

As Help Authors, we often treat online help as a 'thing,' not an activity. We’ve favored the noun over the verb! This preference is natural for writers, who enjoy producing books. If we hope to survive on a dynamic development team, we must train ourselves away from writing books, toward helping people. This shift means examining the bigger picture and adopting different ways of working.

Sisler, Paul and Catherine M. Titta. STC Proceedings (2001). Articles>Documentation>Help>Online

The Help Landscape: A Mile Wide and 30 Seconds Deep

Two questions any writer must deal with are: 'What do I write about?' and 'How much do I say about it?' Essentially, these questions deal with the scope and the depth of a document. Technical communicators have a tendency to want to document a topic as completely as possible, and we carry this instinct with us when we architect and write Help files. In this column, I challenge that prevalent instinct and offer an alternative way of thinking about the scope and depth requirements of Help systems. The benefits of this approach are, I hope, better Help for users and, for our clients and employers, a more efficient use of technical communicators' time. First, I'll discuss three principles that underpin my perspective, then I'll give some practical advice about writing Help that people will actually use.

Hughes, Michael A. UXmatters (2007). Articles>Documentation>Help>Online

Help! It's Not Just a Beatles Movie

Windows Help has steadily improved to the point where the Windows XP Help and Support Center provides nearly exhaustive answers to your queries. Here’s how the Help and Support Center works.

Crawford, Sharon. Microsoft (2001). Articles>Documentation>Help

Help! Six Fixes to Improve the Usability of Your Online Help  

Tight deadlines and limited resources often force wiiters to cut corners and release less than optimal help system designs. After considerable trial and error, I te come up with a checklist that can help you evaluate and improve your help system for the next release. Each question represents an important usability issue.

Timpone, Donna. STC Proceedings (1997). Articles>Documentation>Online>Help

Help.Longhorn - What is it?

The Help platform for Microsoft Windows is changing once again. Since 1995, Microsoft HTML Help has been the standard for Help systems for Windows applications, but the release of the next generation Windows operating system in 2005 will see a brand new XML-based Help platform. It is currently known as Help.Longhorn, or "Longhorn" Help, or sometimes as Help3 or TrésHelp.

Self, Tony. HyperWrite (2004). Articles>Documentation>Help>Microsoft Windows

HelpHook

This is a very simple example of integrating a J2SE application with the Apple Help Viewer application. This sample code has been updated to include a project that produces a universal binary. No code changes were required for it to run correctly on Intel-based Macintosh computers.

Apple Inc. (2007). Articles>Documentation>Help>Macintosh

Helping Users Become Experts

Helping users move from being perpetual novices to experts is a tough task. As this blog post argues, good documentation helps. But you also need to create a product that users can be passionate about.

DMN Communications (2008). Articles>Documentation>User Experience

Hero Stuff: Saving 50% on Support Costs with Fax and Modem Support Documents  

In the PC products market, customers insist on excellent support at rock-bottom prices. The traditional model of customer support, having a phone technician answer customer questions, is becoming too expensive.

Brown, Constance C. STC Proceedings (1993). Articles>Documentation>Online>Help

Heuristic Inspections for Documentation – 10 Recommended Documentation Heuristics

We all are familiar with Jakob Nielsen's heuristics for evaluating the usability of interfaces. When I was conducting a study on documentation usability, I started wondering if there existed a similar set of heuristics for evaluating the usability of documentation. The natural place to pose such a question was the STC Usability SIG mailing list. The response was that there was no heuristics set available although someone had tried to open the discussion in the mailing list some time ago. An answer, which led to the list of heuristics presented below, was something along the line 'Well, now that you asked, why don't you put the heuristics together' and so I did.

Purho, Vesa. Usability Interface (2000). Articles>Usability>Documentation

Hidden Factors of Documentation Quality -- Part 1

The first impulse of many documenters is to turn our work over to editors and graphic designers, or to form committees and develop style guidelines. All of these measures are useful, but none can assure us of quality when there are basic problems with the way we go about producing documentation.

Sesnovich, Bruce A. Boston Broadside (1993). Articles>Documentation>Quality>Technical Writing