Developing a Style Guide in the Real World  

Style guides present a series of rules for standardizing writing. Style guide developers run the risk of concentrating too much on these rules, and too little on other factors that may ultimately affect the quality of the documents that are governed by the style guide. I would like to consider some of these other factors in this paper. I’ve drawn this discussion from Battelle’s efforts developing style guides in various industries. Another reason to involve your clients in the development process is to help ensure that the style guide includes the information they will need. For example, we included tips on using Microsoft Word in a style guide that would be used by writers working in Word. Don’t be afraid to be creative when deciding what to include in your style guide; if it gives writers a reason to look something up in the style guide,

Wieringa, Douglas. STC Proceedings (1996). Presentations>Documentation>Style Guides

Developing Documentation Process  

This paper defines a good manual to have a good balance in quality, cost (close to estimation, not over), and delivery (on time schedule). Analyzing our past problems, we have been developing documentation process to control these three factors through the following: working as a team, standardizing an estimation method, and standardizing an evaluation system.

Suzuki, Akihiko. STC Proceedings (1993). Presentations>Documentation>Workflow

DocBook: An Introduction for Technical Writers  

A set of slides that gives a brief introduction to DocBook and why it is useful for technical writers. Also available in PDF format.

Nesbitt, Scott. DMN Communications (2002). Presentations>Documentation>Standards>DocBook

Document Development: Getting the Technical Writer Involved Up Front  

Working in close cooperation with the chief subject-matter expert (SME) for a major group of documents, we changed the document development process. Instead of having a SME write a draft-leaving the technical writer function as secretary, editor, and layIout technician—we involved the writer from the beginning of the project. The result was a cleaner, neater document development process; a better document; and a lot less trouble for all concerned.

Remington, Thomas F. STC Proceedings (1995). Presentations>Documentation>Methods

Effects Of Documentation Errors On User Perception Of Interactive Programs: Conclusions And Results  

Defining the quality of information has long been a controversial item. Many different theories and methodologies have been brought forward; almost all share at least one common basis— Typographical errors lower the perceived quality of information. In this experiment, the first of a planned, series, we examined the effects of typographical on the user’s perception of the quality of the product and documentation. The conclusions of this first study, and the implications we can make draw them, are presented in this paper.

See, Edward J.P. STC Proceedings (1994). Presentations>Documentation>Assessment

Effects Of Documentation Errors On User Perception Of Interactive Programs: Results  

It would be useful to determine how much effect errors in product documentation have on users, if errors do not seriously interfere with product use. In an effort to start collecting information on this issue, we designed an experiment to explore the reactions of users to a simple interactive program with flawed documentation. We hypothesized that the product quality would be judged in part by the quality of the documentation, if the errors in the documentation interfered with task performance. We also hypothesized that some but not all users would be sensitive to documentation errors and would downgrade their rating of the program and the documentation based on these errors. The results of our experiment are presented in this paper.

Ridgway, Richard K. STC Proceedings (1994). Presentations>Documentation>Assessment

The Effects of Online Systems on Documentation Management  

Online tools can improve documentation management in several ways, depending on management goals of cost, schedule, or quality. Cost management tools need integration with automated status and quality assessment tools. Workflow simulation tools show great promise for avoiding bottlenecks in the document development process. Automated tools can enforce quality checkpoints and provide model document templates. The continual evolution of online documents will require new management approaches and goals.

Reilly, Annette D. STC Proceedings (1996). Presentations>Documentation>Online

An End-to-End Process for Creating and Validating Scenario-Driven Documentation  

This paper describes the end-to-end approach we used to create and validate scenario-driven information for a new product. This approach focuses as much on designing and testing information as it does on writing the information.

Newman-Collins, Ann and Linda Streitfeld. STC Proceedings (2000). Presentations>Documentation>Assessment

Enhancing The Review Process: Giving And Receiving Constructive Feedback  

Clear, positive feedback can contribute significantly toward improving the quality of printed and on-line documentation. Wizen feedback is negative, unclear, or incomplete, however, the accuracy and quality of a document can suffer, and misunderstandings between colleagues can result. Those who are responsible for reviewing documental ion can enhance that process by knowing what type of feedback to provide and how to offer it in a clear and constructive way. Those who request feedback on their documentation projects also can enhance the review process by clearly identifying the project scope and specifying their evaluation needs to their reviewers.

Pritchard, Laurie N. STC Proceedings (1994). Presentations>Documentation>Workflow

Evolution to Performance Support: From Help to EPSS to PCD  

TimeCorp, a leading publisher of commercial labor management software, has been working to incorporate increased levels of user support within its software interface. In this case study we will present samples of the TimeCorp product support as it evolved over time, from the initial online help to the electronic performance support (EPSS) prototype to the performance-centered design (PCD) solution. The types of information provided in the support also evolved to match the mode of presentation. The documentation team led this evolution within the organization and their roles have changed as a result.

Battle, Lisa H. and Metta Johnson. STC Proceedings (2000). Presentations>Documentation

Finding the Best Mix of Paper and Online Documentation: A Case Study  

The concept of the “paperless oflce” has become popular with executives who want to reduce costs and users who, often with good reason, refuse to open a manual. Technical communicators, who often understand the practical flaws behind this concept, must be prepared to make smart decisions about what information to present in manuals and what to present online. They must also justljj to management their decisions either to resist moving everything online or tofkd creative ways to do so without forgetting about the needs of the user.

Jones, Chip. STC Proceedings (1997). Presentations>Documentation>Online

From Purchase to Productivity: Bridging the Documentation Gap  

Marketing documentation entices clients to buy your products. Technical documentation tells clients how to use your products.

Alexander, Bruce, Avis French and Elaine Randolph. STC Orange County (1998). Presentations>Documentation

Honey, I Shrunk The Manual  

The writers at Software Publishing Corporation faced the challenge of reducing the page count of their manuals by more than 50%—without sacrificing quality, extending the schedule, or starting from scratch! They found that approaching this daunting task from several different directions at the same time proved to be the most effective. While the following tips apply primarily to DOS and Windows software manuals, the tips are a good starting point for streamlining any documentation set. The benefits include cutting dollars from the per unit cost of goods and promoting greater customer acceptance of documentation as a learning tool.

Repel, Timothy R. and Jennie Tan. STC Proceedings (1994). Presentations>Documentation>Methods

HTML Help: Transition Without Fear  

You need not be a programmer to begin producing effective, attractive HTML Help or Webpages. You can use pubiished tempiates andauthonng toois and study an existing page’s HTML code to heb you produce pages whiie you learn. Templates allow you to add your content to existing skeleton pages. You can also use an HTML or HTML Heip authoring tooi to create your help. HTML Heip authoring tools aiiow you to add WinHeip-like functionality and ~eamnce to your HTML Hefppages. Using your browser and a text editoc you can study HTML code frum an existing Webpage. Using these methods, you can learn HTML while already producing effective Heip.

Lambert, Twyla Beth and J. Suzanna Laurent. STC Proceedings (1997). Presentations>Documentation>HTML

An Information Make-Over for Performance Centered Design  

Technical communicators have long harbored a secret that we are reluctant to admit to outsiders: Users don’t like reading manuals. They do it only as a last resort. Even online help systems, which we originally hoped would be easier to use, have not met with great enthusiasm among users. It’s an all-too-common dilemma – there is a lot of information that could be explained, but users struggle along as best they can without it. Part of the problem has always been that users are reluctant to leave their work to seek information -- and rightly so. They have work to do and deadlines to meet. Even if your manual or online help contains a wealth of useful information, it takes them away from their work and interrupts their train of thought. If they do try to use it, the help window typically overlays the interface and adds its own set of navigation, resizing, and searching issues.

Battle, Lisa H. STC Proceedings (2000). Presentations>Documentation>Information Design

Introducing DocBook

Structured documentation is semantic, rather than presentational. Components have identifiable structure. HTML and Word are somewhat structured. DocBook is strictly structured.

Walsh, Norman. NWalsh.org (2001). Presentations>Documentation>Standards>DocBook

Is Online “lnline” with Your Users’ Needs?  

In preparation for the next release of our flagship so~are product, the International Publications Department at Waters Corporation wanted to assess the usefulness of our current product software documentation with the idea of moving the next generation of documentation in the direction requested by our customers. Based on extensive customer contact, we formulated a plan to dramatically revamp the documentation, namely to replace the paper user’s guides and transform our existing online Help into a comprehensive Online User’s Guide.

Kroeber, Kurt A. and David L. Kelley. STC Proceedings (1997). Presentations>Documentation>Help

The Key for Effective Documentation: Answer the User’'s Real Question  

To successfully communicate to users, documentation must do more than meet the user’s information needs, it must present the information in the same way the user processes the information. The design of sofhYare and its accompanying documentation must be reconceived so that the design is done porn the problem-solver’s pornt of view. Effectively designing documentation requires the writer to: start with the user, answer the user’s rest questions, optimize all documentation as a smgle umt, allowfor user mistakes, and consider how you present the information.

Albers, Michael J. STC Proceedings (1997). Presentations>Documentation>Help

Low-End Online Documentation Viewing Systems: Why and How  

Online documentation is now widely accepted for its convenience and cost savings. However, some small, non-Windows shops find very few offerings in the market place for online documentation software.

Sonnenberg, Beth Apple. STC Proceedings (1995). Presentations>Documentation>Help>Online

Managing Modular Documentation Using a Database  

While implementing a Modular Documentation Method and the development of Responsive Hypermanuals (Lettvin, 1999), concerns were raised as to how to effectively manage the potential explosion of seemingly fractured document components (modules) while maintaining key infrastructure and quality assurance mechanism already in place. This paper examines one unique solution to this problem: building a web-based database application that manages and tracks modules, documents and resources for any documentation project. In addition, it has a built-in structure for handling a robust documentation process. Some advantages and obstacles in developing a modular documentation database solution for the web are discussed.

Earley, James M. STC Proceedings (2000). Presentations>Documentation>Online

Mental Processing of Online Documentation: From Concepts to Applications  

This panel will review the existing literature on how we mentally process online documentation and describe some implications for effective online document design. We invite the audience to define with us some critical areas for further research.

Knodel, Elinor L., Henrietta Nickels Shirk, Candace Sodetston and James Thibeau. STC Proceedings (1997). Presentations>Documentation>User Centered Design

Mike Hamilton Gives Flare Demo to the STC Suncoast Chapter

Mike Hamilton from Madcap Software visited the Suncoast chapter in Tampa, Florida, and presented on Flare. In this presentation, he talks about the story behind RoboHelp and Macromedia/Adobe (this blew my mind). He also provides a lot of inside detail on Flare.

Hamilton, Mike and Tom H. Johnson. Tech Writer Voices (2007). Presentations>Documentation>Software>Madcap Flare

Mobile Manuals for Mobile Professionals  

PDAs raise new opportunities for technical communicators to provide corporate information in a compact, electronic package.

Buckley, Susan. STC Proceedings (2001). Presentations>Documentation>Online>Mobile

Modelling Information, or Documentation Planning for Dummies  

Identify the user. Identify the user's goals. Drill down to task level. Establish what the user knows. Identify what the user needs to know. Identify what the user should NOT know.

Skau, Edwin. STC India (2003). Presentations>Documentation>Project Management