Building the Treasure House: Creating Knowledge Bases on the World-Wide Web  

Web knowledge bases offer an excellent platform for delivering technical documentation and customer support information. They also represent an area of great opportunity for technical communicators to expand their skills, satisfy their customers, and create value for their employers or clients. This session explores the components of a web knowledge base and the tasks involved in planning and building one.

Massa, Jack A. STC Proceedings (1998). Articles>Documentation>Online>Web Design

Designing Help Text

In an ideal world help text would be unnecessary - users would never get stuck in an application or site. It should be enough to provide clear design, carefully chosen titles and labels for the various functions, appropriate field prompts when user entry is required, helpful feedback, a glossary, and 'embedded' help such as default values, example input, on-screen step-by-step instructions and explanatory text next to fields or functions. Help features should certainly be a last resort. Anyone embarking on adding it to an application or site should be sure that they have already followed the best practise listed above. In most cases (certainly online) a help option should not be necessary.

Farrell, Tom. Frontend Infocentre (2001). Design>Documentation>Help>Online

Designing User Assistance for Internet Marketplace Applications Using Server-Side Online Help    

In this article, I examine Internet marketplace applications and the challenges they present to user-assistance design. This examination illustrates the ways in which complex Internet applications, such as marketplaces, force technical communicators to rethink their approach to online user assistance. In the course of this examination, I make a case for a model of user assistance that taps the potential for customizability, scalability, and dynamic content of the technologies that power Internet applications. However, marketplaces are only one example of the type of application that can benefit from this model because it can be implemented for any Internet or intranet application that utilizes dynamic, build-on-the-fly Internet technologies, such as Microsoft Active Server Pages or Sun Microsystem JavaServer Pages. To fulfill our responsibilities to our users, we technical communicators must be willing to expand our skill set by adopting these technologies that allow us to target documentation to user needs.

Whittemore, Stewart. Technical Communication Online (2003). Design>Documentation>Online

Developing a Single-Sourced Online Help System    

The definition of single sourcing continues to broaden in scope since its first mention in The Society of Technical Communication’s 46th Annual Conference publication. As a result, it is becoming increasingly difficult for technical communicators to understand what single source means and, more importantly, choose a definition of single sourcing that correlates with their specific task. One “type” of single sourcing involves reusing information for multiple products. Several developers at IBM have produced a single-source online help system. Unlike other single-sourcing methods that require a significant investment and a high degree of technical experience, these methods are inexpensive and require a moderate, yet creative, technical aptitude.

Vicek, Keith, Phil Menzies and Andre Evans. STC Proceedings (2002). Design>Documentation>Single Sourcing>Online

Electronic Catalogs: Graphics    

A compilation of the most frequently asked questions about graphics in electronic catalogs. You will find answers to general as well as to technical questions.

ITEDO Software (2003). Design>Documentation>Graphic Design>Online

Helpmaster

Here you will find the world's largest selection of WinHelp, HTMLHelp and HTML related files and hints.

Helpmaster. Design>Documentation>Online

Information Layering: Providing Need-Based Information

Information Layering is not new, but it has acquired a new dimension through modern technical and interactive possibilities. Even as of now, this technique can be used to make HTML-help considerably more user friendly.

Achtelig, Marc. indoition engineering (2005). Articles>Documentation>User Centered Design>Online

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

Issues with Adobe FrameMaker Print to PDF

An issue that has come up over and over again on several FrameMaker and Acrobat/PDF email lists as well on the corresponding Adobe User-to-User forums is that of creation of PDF files. FrameMaker 5.5.6 and 6 have what looks like a convenient feature that is supposed to allow you to create PDF files via simply saving the document as a PDF file. I have gone on record as advising end-users not to use this approach for reliable creation of PDF files from FrameMaker documents under Windows and MacOS with FrameMaker 6 and earlier. Why do I most vociferously offer this advice and why doesn't the problem get fixed? And how SHOULD you create PDF files from FrameMaker?

Isaacs, Dov. Bright Path Solutions (2004). Articles>Document Design>Online>Adobe FrameMaker

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

Non-Fatal Errors: Creating Usable, Effective Error Messages

It's often easy to identify what kinds of error messages don't help users, but it can be tricky to avoid them, and even more of a challenge to create the opposite: error messages that give users a clear indication of the problem, offer information to help them fix it, and provide tips on how to avoid the same situation in the future. This paper details the steps involved in creating understandable, helpful error messages, and suggests ways of communicating the value of good error messages to managers and executives.

Wilska, Emily. WritersUA (2004). Articles>Documentation>User Centered Design>Online

Online Documentation: Design Issues

Designing online documentation? You mean I can’t just take the word processing file and make it available on our network, or throw the document into a Windows Help file and ship it? Well, I would not recommend either of those options. You should take many things into consideration when you design an online document.

TechCom Plus (1999). Design>Publishing>Documentation>Online

Restructuring Online Documentation for the World Wide Web  

Technical communicators around the world are turning to the World Wide Web us their primary delivery agent for on-line documentation. The transition from older forms of on-line documentation to HTML-based documents pre - sents new challenges in every phase of the documentation process: document creation, layout, access, and especially hypermedia capability The constant development of new web tools presents an even greater challenge for an organization seeking to stay abreast of technology with an ever decreasing budget. This panel will outline the basic steps in migrating to the web while focusing on one organization’s solution to meeting the challenges of restructuring its on-line documentation for web migration.

Goode, Christina M., Jennifer Campbell and David Hale. STC Proceedings (1996). Articles>Documentation>Web Design>Online

Single Source Documentation for Today

What happens when the software firm you work for decides it will not deliver large printed manuals any more? Then the request comes to put everything online. Six months later, user profiles shift to the World Wide Web and you're asked to deliver HTML. In the future, a database of SGML information chunks may let us deliver anything, any which way.

Stieren, Carl. Simware (1997). Design>Documentation>Single Sourcing>Online

Strategies for Producing Browser-Based Technical Documentation

This Technical Note attempts to provide a few good strategies for resolving some of the issues around producing and viewing Web-based technical documentation. The Note may be useful for engineers, technical writers and content producers who must wrestle with issues of producing documents such as ReadMe files, Release Notes, technical articles, and other forms of technical communication that land on the Web.

Apple Inc. (1996). Design>Documentation>Help>Online

Using Perception in Managing Unstructured Documents

Over the last ten years, the increased availability of documents in digital form has contributed significantly to the immense volume of knowledge and information available to computer users. The World Wide Web has become the largest digital library available, with more than one billion unique indexable web pages. Yet, due to their dynamic nature, fast growth rate, and unstructured format, it is increasingly difficult to identify and retrieve valuable information from these documents. More importantly, the usefulness of an unstructured document is dependent upon the ease and efficiency with which the information is retrieved. In this paper, we define an unstructured document as a "general" document that is without a specific format e.g., plain text. Whereas, a document divided into sections or paragraph tags is referred to as semi-structured e.g., a formatted text document or a web page.

Cheng, Ching Kang and Xiaoshan Pan. ACM Crossroads (2004). Articles>Document Design>Online>Cognitive Psychology

What's Next for Text?

All text is digital in origin. Fixed print has become printout, one substrate of expression for a preexisting digital code. And it is no longer the only game in town. Other, digital, displays–--regular cathode ray tube computer screens, liquid crystal display flat screens, book-sized electronic display devices, digital screen projectors, heads-up displays, goggles, helmets, immersive virtual reality environments–--now compete with the printed page for final display. These digital displays can recreate the full electronic expressive space, a three-dimensional, dynamic world, as the flat, fixed world of print cannot. Fixity stands at the center of Beatrice Warde's brave declaration: 'not to perish on waves of sound, not to vary with the writer's hand, but fixed in time.' That fixity comes unglued in the diversity of display devices in which text can now become manifest. Text will find its future as the various ways we can now display it compete for the privilege.

Lanham, Richard A. Education Communication and Information (2003). Design>Document Design>Online

Where Is the Instruction in Online Help Systems?    

One of the ironic things about online help systems is that they are very often not helpful and even increase the user's frustration and stress level. This increased frustration sometimes results in the rejection of the software. One solution is to increase the effectiveness of online help systems by designing them from an instructional design perspective. Some of the things we can provide users include: imperative, task-focused procedures; graphic feedback; access to redundant instructions; links to tutorial practice; philosophical and conceptual explanations for 'why' they are completing specific tasks.

Pratt, Jean A. Technical Communication Online (1998). Articles>Documentation>Instructional Design>Online