Online, On Time: Developing an Online Documentation System Using Five Easy Tools  

So, you need to distribute your documents on the Internet in addition to the hundreds of other things you already do? As you may have already discovered, coding everything in HTML is not exactly the solution high-volume technical writing departments are looking for. We understand. We’ve been there and, in the process, have developed a system to make it as painless as possible. The following is a brief synopsis of our system. We will cover the details more thoroughly in our demonstration.

Wright, Lori and Sandy Sledge. STC Proceedings (1999). Articles>Documentation>Online

Open Source Documentation

Collaborative technologies are supplanting traditional channels for product tech support.

Udell, Jon. InfoWorld (2005). Articles>Documentation>Open Source

Orr's Aphorisms About Tech Writing

A collection of hints and advice about documentation and usability from David Orr (one of our Institute instructors and the founder of the first usability lab in Chicago).

Abbott, Christine. Northern Illinois University. Articles>Documentation>Usability

Our .CHM Files Don't Work Anymore. Why?

If you are delivering your help from a network location and you notice that .CHM files don't work anymore, don't be surprised. Recent Microsoft updates include tighter security for .CHM files. After installing the updates you can no longer run .CHM files from a network location. However, you can still run a .CHM file on your local machine.

HelpScribe (2008). Articles>Documentation>Online>Help

Review: Our Little Help Machines and Their Invisibilities    

This paper examines the four kinds of invisibility Johnson-Eilola associates with minimalist help systems: fast information access that reduces user reflection and questioning, impersonal writing style that assumes the Shannon-Weaver communication model, narrow scope that leads to training but not teaching, and interface designs that oversimplify user tasks. For each of the four, the paper questions Johnson-Eilola's conclusions. Ultimately, the problems with truncated online help systems may disappear, as help systems are increasingly linking to the web, where adequate conceptual information is often supplied and opportunities for a social context for help are available.

Farkas, David K. Journal of Computer Documentation (2002). Articles>Reviews>Documentation

Outsourcing Documentation Development: Assessing the Offshoring Option  

This paper discusses some of the aspects that should be considered when evaluating the required resources and total cost of offshoring documentation development. The actual metrics for assessing offshoring costs are not included in this paper. Rather, it is suggested that you take each of the topic areas and measure the costs as they relate to your specific situation. It is only after factoring in the dollars related to these activities that you and your company’s executive team can make a complete assessment of offshoring’s potential financial benefit.

Clifton, Deborah. STC Proceedings (2005). Articles>Documentation>Outsourcing>Offshoring

An Overview of JavaHelp 1.0 and Doc-To-Help 2000  

JavaHelp is a new online Help platform created by Sun. Sun released JavaHelp 1.0 in April, but it's been publicly available through several beta releases for a while. (The just-released Doc-To-Help 2000 supports this new version of JavaHelp.)

Bannister, Bob. ComponentOne (1999). Articles>Documentation>Online>Help

Paper and Online Documentation Trade-Offs

This article first describes the basic types of user. It then lists the advantages and disadvantages of typical paper and online documents and relates these to the various user types. Finally, there is a comparison of the paper and online formats with respect to usability criteria.

Unwalla, Mike. TechScribe (2003). Articles>Documentation

Paper to CD-ROM: A Case Study in Converting from Paper to Online Documentation  

Cisco Systems, Inc., releases a CD-ROM volume each month that contains documentation for all versions of products currently in use. Cisco spent 8 months preparing for the release of the first CD Regular monthly releases require adherence to a strict schedule of incorporating errata and enhancements into online manuals, placing new and revised books into a CD database, resolving problems that occur during the build, and testing that all books are in their proper locations. This process has affected how managers schedule documents so that they are included on the CD that is current when a product ships. It has also changed the roles of the writers and editors, who must now manipulate files in the CD database and incorporate errata and enhancements into both paper and online documents.

Cote, Joanna C., Elizabeth R. Fitch, and Aviva Garrett. STC Proceedings (1995). Articles>Documentation>Online

Peaks and Pitfalls of Implementing a New Documentation Strategy  

In 1993, Compaq Computer Corporation ventured into a totally different market--the consumer market. Once known primarily as a company that manufactured high quality, expensive business computers through its elaborate dealer network, Compaq was faced with selling its units to consumers through retail outlets. As a result, the PC Marketing Communications department concluded that its current documentation set was not giving the students; retirees; homemakers; and small business owners, who work out of their home offices, the kind of information they needed to be productive. This led the department to the challenge of creating a new documentation set that would meet the needs of these new customers.

Clifton, Deborah, Deborah R. Crockett, Diana Jaques and Sharon B. Jones. STC Proceedings (1995). Articles>Documentation>User Centered Design

Performance Test Report: Comparative Research of Understanding-Oriented and Operation-Oriented Manuals  

For the dial registration task of a facsimile machine, we prepared an 'understanding-oriented manual' for better understanding of the relationship between purpose and procedure and an 'operation-oriented manual ’’for more accurate descriptions of procedures. We also classified users into 'understanding-oriented users' and 'operationoriented users' by means of instructions and evaluated the relationship between manual types and users through performance tests. We found that understanding-oriented users enhanced their work efficiency more with the understanding-oriented manual than with the operation-oriented manual, while the operation-oriented users did not show any sign of improvement with either manual.

Kawaguchi, Shiro. STC Proceedings (1996). Articles>Documentation

Performing Publications Needs Assessments  

A publications needs assessment is a way to identify and analyze documentation and publishing needs for a project, group or company. The technical communicator can use these assessments to ensure that the proper documentation and publishing services are provided. This paper describes a four step approach to performing publications needs assessments.

Devlin, John T. STC Proceedings (1993). Articles>Documentation>Planning>Assessment

Photo-Tracing

One of the most effective methods of creating a technical illustration is the photo-tracing technique.

ITEDO Software (2001). Articles>Documentation>Technical Illustration

Pictures for Procedures  

Illustrations for procedural documents should show actions from the mental perspective of people carrying them out. Illustrations also should take into account the twodimensional displays of printed documents and computer screens by orienting critical body positions and movements across displays.

Krull, Robert. STC Proceedings (1999). Articles>Documentation>Technical Illustration

Planning an Online Help Project

This paper outlines some general principles you need to consider when planning an online help project and creating WinHelp files.

Hollis Weber, Jean. Technical Editors Eyrie (1999). Articles>Documentation>Online>Help

Planning and Creating a Windows Online Help System  

The basic requirements for creating accurate and useful technical documentation are good writing skills, an understanding of the audience, knowledge of the tools used for producing documentation, ability to use the product, and ability to successfully interview subject matter experts. While the same skills are essential for creating an online help system, writers also need to understand how help projects are set up, how to modify their writing to produce modular help topics, how to test the program-to-help links between the product and the help topics, and how to align help file development with engineering build dates. In addition, writers expand their hypertext awareness to include new terms such us jumps and pop-ups.

Mandavilli, Lavanya K. STC Proceedings (1995). Articles>Documentation>Online>Help

Planning and Designing Multimedia  

Multimedia can add another dimension to electronic documentation (Help and manuals) and computer-based training. The process of planning and developing a multimedia project draws on new skill sets. This workshop focusses on the key role of the technical writer as writer, designer, and project manager.

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

Planning for DITA Success Part Two: How to Deploy DITA, Step-By-Step  

This paper, the second of a series, closes the loop by examining implementation issues from a technical perspective. It explores best practices within the five key steps of a successful transition.

Manning, Steve. Rockley Group, The (2007). Articles>Documentation>Standards>DITA

Planning for Factors That Affect Project Cost  

Documentation projects often change to respond to changes or obstacles in the system development process. Sometimes, these changes increase project costs. However, as corporate budgets tighten, project managers are frequently asked to work within their original estimates despite the changes. To minimize these situations, project managers need to identify the factors that can increase the costs of a project, evaluate the chances of problems arising, and adapt the work plan and estimate to anticipate the problems that are outside of their control.

Fredrickson, Lola and Joyce Lasecke. STC Proceedings (1994). Articles>Documentation>Management>Estimating

Planning Multimedia Segments  

Multimedia can add another dimension of information to online documentation. This progression discusses the optimum methods of presenting information (text, graphics, multimedia) and the planning and design process.

Rockley, Ann. STC Proceedings (1995). Articles>Documentation>Multimedia

Podcast: Using Video in Training and Documentation, Interview with Todd O’Neill

In this podcast, rich media specialist Todd O’Neill explains how to add video to your training and documentation deliverables. Many technical writers are intimidated by the learning curve, equipment costs, and software they think they need to create video, but actually you can create engaging videos with minimal equipment (e.g., $150 for a Flip video camera) and using software you probably already have (e.g, Windows Movie Maker or iMovie). In this podcast, Todd lays out the basics for those who know nothing about video. He explains the equipment you need, techniques for minimizing editing time, ways to publish the video online, filming techniques to focus on, and creative ways to package your video for your users.

O'Neill, Todd and Tom H. Johnson. Tech Writer Voices (2008). Articles>Interviews>Documentation>Multimedia

Policies and Procedures Can Help Your Organization

Compliance and meeting operational needs are two very important reasons for implementing a system of policies and procedures.

Bizmanualz (2007). Articles>Business Communication>Documentation>Policies and Procedures

Policy and Procedure Communication and the Lone Writer  

As a lone writer developing policy and procedure documentation, many of us face what appear to be insurmountable hurdles in reaching our intended goal – useable documentation that accurately reflects the business’ operations. It usually begins with trying to get everyone to take the need for P & P documentation seriously. This can be followed by frustrations in getting the information required to write coherent and useful documentation. Then there is the need for standards for which no one sees the importance – ‘just a whim of the writer’. Add to this volatile mix the requirements of many international standards impacting how business is conducted, and you wonder why anyone in right mind would take up the challenges of this field of writing. But it really can be fun and a very rewarding field of endeavor.

Mason, Susan, Rich Maggiani, Julia Margulies and Ralph E. Robinson. STC Proceedings (2002). Articles>Documentation>Policies and Procedures>Business Communication

Posting User Documentation on the Web  

Our company posts user documents on its Internet web site as PDF files. Announcements are sent to customers and company staff to inform them of the latest document updates. Customers log on a password- protected documentation page, where they can view the documents in a Reader or save them to their PC hard drives. There are several advantages to distributing documents in PDF on the Internet for both customers and our company.

Utz, Dana. STC Proceedings (2003). Articles>Documentation>Online>Adobe Acrobat

PowerPoint Tutorial: Microsoft PowerPoint 2003

This PowerPoint tutorial is just what you need to get up to speed using PowerPoint to create engaging and effective presentations. Whether you're creating a presentation for an informal gathering, a school or classroom assignment, or one for your business partners or associates, PowerPoint is a powerful tool that will help get the job done. Each PowerPoint tutorial features text and screen shots, and some include narrated multimedia tutorials in Flash.

Guides and Tutorials (2006). Articles>Documentation>Presentations>Microsoft PowerPoint