Adapting Traditional Editing Practices for Online Documentation

Developing a process and using guidelines for editing online documents, both rooted in traditional editing practices.

Fink, Bonnie L., Carol E. Gasser, Jennifer L. Giordano and Beth A. Williams . STC Orange County (1998). Presentations>Documentation>Editing

Animation as Documentation: A Replication with Reinterpretation  

Animated demonstrations are replacing text as the vehicle for documentation, help, and training on new software systems. An animated demonstration is a demonstration of a particular feature or features by a ghost user. The demonstration executes the procedure for performing a task, on-screen, as the user passively watches. Whereas research into the effectiveness of animated demonstrations has produced mixed results, certain patterns of behavior are emerging. The current study replicates the learning advantage offered by animated demonstration and shows that retention is equal to that of a group instructed by text after a one week retention interval. Implications for development of on-line training materials are discussed.

Lipps, Audrey W., J. Gregory Trafton and Wayne D. Gray. STC Proceedings (1997). Presentations>Documentation>Interactive

Applying Software Development Methodology to Developing Help Systems  

Help systems have become an important part of the Technical Communicator’s repertoire. If we as communicators approach developing help systems in the same way we approach writing paper documentation, we miss the advantages of using software development methodology.

Nurczyk, Susan V. STC Proceedings (1997). Presentations>Documentation>Workflow

AuthorIT: Time-Saving Techniques Using AuthorIT  

A presentation about techniques one could employ using AuthorIT.

Bracey, Rhonda. CyberText Consulting (2005). Presentations>Documentation>Software

Building a SGML-based Documentation Environment  

SGML (Standard Generalized Markup Language) became an ISO-approved standard and was adopted as a Japanese Industrial Standards. Recently, SGML has begun to be used more widely in Japan. We, the Corporate Design Center of Ricoh Company, Ltd., have completed development of the a single SGML module DTD (Document Type Definition), customization of a SGML editor, and the implementation of review system using the world wide web. In addition, we have developed an automatic DTP system based on SGML.

Mimura, Kaori. STC Proceedings (1998). Presentations>Documentation>SGML

Building Documentation into the Interface

As documentation is more and more built directly into the interface, and as technical communicators move into interface design and usability, it is important to have a theoretical framework within which to make decisions about what kind of information will be conveyed at any moment. We can build on basic principles of cognitive psychology to help us make these decisions. We start from a question: Why should users be aware of the difference between interface and documentation when all they want is to get something done?

Quesenbery, Whitney. STC Orange County (1998). Presentations>Documentation>Usability

Building the Treasure House: Creating Knowledge Bases for the World Wide Web

What is a knowledge base? What are the components necessary to build one?

Massa, Jack A. STC Orange County (1998). Presentations>Documentation>Information Design>Databases

Canon Elura 50

Information about how to use the Canon Elura 50 camcorders for technical communication multimedia.

Arnold, Jenni and Christina Kitson. Studio for New Media (2004). Presentations>Multimedia>Documentation>Video

Communicating Design: Web Design Documentation

An overview of web design methods, including a survey of questions one should ask during the process.

Brown, Dan. SlideShare (2006). Presentations>Web Design>Documentation

Comparing Help Authoring Tools

Help authoring tools are big in today’s market. Matthew Ellison quoted one source as saying that there were 208 Help authoring tools. A veteran with over 10 years Help authoring experience, Ellison shared information on selecting authoring tools.

Boos, Diane and Matthew Ellison. STC Puget Sound (2004). Presentations>Documentation>Software>Help

Concrete Methods that Promote Active Learning in Software Manuals  

To learn software, passive users prefer to have concepts and procedures clearly spelled out for them, while active learners prefer experimenting with the program. When designing a manual, writers should keep both types of users in mind. Writers at WordPerfect are currently experimenting with minimalist design models that encourage active learning. One such model is an “On Your Own” section which guides users through creating a document. Another model is a visually oriented “Applications” section which provides tips on how to create a document.

Bringhurst, Robert G. STC Proceedings (1993). Presentations>Writing>Documentation

Creating an Interactive Online User Guide  

Want to create a colorful, interactive online version of your FrameMaker® documents? Not many steps are involved in making the conversion: start with template changes in the FrameMaker files; create a postscript file; convert it into a PDF (Portable Document Format) file using Adobe Distiller®; and add final touches to the PDF file in Adobe Exchange®.

Beren, Wendy G. STC Proceedings (1998). Presentations>Documentation>Online>Adobe FrameMaker

Creating Award-Winning Computer Servicing Documentation  

Creating award-winning computer servicing documentation involves knowing something about customer service engineers, what content to provide, what kinds of art work best in different contexts, and differences in producing hard copy vs. online documentation. If you want to move from writing software or marketing documentation, find a good mentor to help you gain experience with these elements.

Nelson, Dennis T. and Donald C. Phippen. STC Proceedings (1999). Presentations>Documentation

Creating ERP Documentation for End Users  

How do you create ERP documentation for your end users? One key is to map the five phases of the ERP documentation creation process to the phases of an ERP system implementation. Phase 1 is primarily for analysis, phase 2 is for the design process, and phase 3 consists of the actual building of the documentation. During phase 4, you should finalize all building and testing of the system. During phase 5, you should research end user trouble spots and continually improve the documentation in those areas.

Canobbio, Donna K., Jennifer A. Durbin and Lori K. Spahr. STC Proceedings (2000). Presentations>Documentation

Creating Help in the Web 2.0 Age

This is a presentation titled 'Creating Help in the Web 2.0 Age' that Neil Perlin gave to the Suncoast Chapter in Tampa, Florida in February 2007. Neil talks about what Web 2.0 is, and how help can be delivered on the fly according to specific user requests.

Perlin, Neil E. Tech Writer Voices (2007). Presentations>Documentation>Help>Podcasts

Creating Online Help in a Multiplatform Environment  

With the explosion of online help authoring tools (primarily in the Windows® environment) companies are clamoring for the ability to produce online help on multiple platforms. This demonstration presents one solution to the problem of creating online help in a multiplatform environment. We will demonstrate the process of translating FrameMaker™ files from the Macintosh® to Windows NT®, and ultimately, to UNIX®.

Shelton, Jan D., Anne Navarro and Robbie Fontenot. STC Proceedings (1996). Presentations>Documentation>Help>Adobe FrameMaker

Decision Making: A Missing Facet of Effective Documentation  

The old school of software interface design and document writing took the view that if the user could find the information someplace, the user could use it. But simply sticking in details ignores how readers access and process information.

Albers, Michael J. ACM SIGDOC (1996). Presentations>Documentation>Management

Designing a Supplementary Web-Based Online Help System: A Case Study  

Computerized Medical Systems, Inc. (CMS) has implemented an extensive online help system based on HTML for its FOCUS radiation therapy planning system. Netscape Navigator was selected as the browser because FOCUS is based on the UNIX platform and Netscape was the only HTML browser available for UNIX.

Watson, Frank. STC Proceedings (2000). Presentations>Documentation>Online>Help

Designing an Online Help System Before the Interface is Ready  

Developing a Windows online help system that clients can use effectively and bringing it in on time and within budget is a challenging task. You can dramatically improve your chances of success by doing the following: Develop help as sofnvae is being developed (and even before!); Chunk information for easy reading and to facilitate reuse by other writers; Create design and style guidelines to cut down peer review and editing time; Develop and use information webs to cut down on technical review time; Integrate the information web and the user interface to complete your help system.

Henselmann, Mary Anne. STC Proceedings (1997). Presentations>Documentation>Help

Designing Effective Single Source Materials  

People often have to create documents for different audiences and for different media, (e.g. web, Help, training). However, timelines and budgets for developing information are often tight. This means we have to find more efficient ways to develop information. One way is to consider single sourcing information for multiple users and media. While single sourcing does take more up-front planning, it can significantly decrease costs and development times once implemented.

Rockley, Ann. STC Proceedings (2000). Presentations>Documentation>Single Sourcing

Designing for the Web: Special Considerations for Safety Information  

Manufacturers are currently grappling with determining whether they should put safety information on the Web and if they do how it should be presented. Technical communicators, Web content developers, and Web designers will ultimately be responsible for the presentation of Web-based safety information. This article discusses special considerations that should be given the formatting (HTML, PDF, etc.), design, (font, size, and color), and location of safety information on the Web. Additionally, areas for future research on the issue of Web-based safety information are identified.

Tallman, Lisa A. STC Proceedings (2001). Presentations>Web Design>Documentation

Designing Multi-Platform Online Help: A Demonstration  

Designing multi-platform online help can be made more efficient by placing special effort in the design of the development plan. If the development plan is broken up into four key elements the resulting multi-platform design will yield a great amount of latitude for both maintenance and future enhancements. During the demonstration we will discuss our use of these elements to design both online and hardcopy documentation to support both a mainframe and a windows interface.

Taylor, Shhonn D. and Pat Straw. STC Proceedings (1996). Presentations>Documentation>Help

Designing Policies and Procedures Information  

The policies and procedures (P&P) developer must address more than format and style issues in designing policies and procedures information. There are at least five levels of design for policies and procedures information. Level 1 concerns the architecture in which the information resides. Level 2 concerns the type of relationship that exists among documents within the architecture. Level 3 concerns the approach used in designing and developing the information content within a policies and procedures document. Level 4 concerns the writing methods to use. Level 5 concerns the various writing techniques for presenting information in units individually and collectively within a policies and procedures document.

Urgo, Raymond E. STC Proceedings (2000). Presentations>Documentation>Policies and Procedures

Designing Responsive Hypermanuals  

The responsive hypermanual is a new method of delivering documentation that orders the contents of an online manual in response to the user’s current task. It uses hypertext modules controlled by an SQL database for managing the development, and presentation of modular documentation to provide a uniquely usercentric system. their needs. When the user asks technical support for help, they delegate the effort of assembling material scattered throughout the document into a meaningful answer.

Lettvin, David W. STC Proceedings (2000). Presentations>Documentation>Interactive

Developing a Documentation Process that Works in a Regulated Environment  

Working in a regulated environment (for example, an ISO-certified company or a company regulated by the FDA) necessarily changes the way documentation is developed and managed. The documentation development process must exist and must meet all of the requirements set by the governing body, yet not be so mired in detail that it overwhelms the writers and managers.

Rupel, Roberta A. STC Proceedings (2000). Presentations>Documentation