How to Write a Report Without Getting Lynched

You put forth your best effort to explain to the stupid sods exactly how and where they screwed up, then they have the temerity to not appreciate your fine efforts. Here's how to write a report that will cause change, instead of uproar.

Tognazzini, Bruce. Nielsen Norman Group (2001). Articles>Usability>Reports>Technical Writing

How to Write a White Paper

A white paper in the high-tech industry is a technical document that describes how a technology or product solves a particular problem. It's a marketing document and a technical document, yet it doesn't go too far in either direction. A good white paper is informative and is designed to show off the advantages of a product or technology.

Knowles, Michael. Writing World (2001). Articles>Writing>Technical Writing

How to Write Copyright Pages  

A well-designed user guide contains a copyright page, which provides copyright information for your company's products as well as for any third-party products mentioned in your document.

Amott, Lyndsey. Docsymmetry (2004). Articles>Intellectual Property>Copyright>Technical Writing

How to Write Instructions

These guidelines are written primarily for people who are not technical writers. If you are new to technical writing, you will probably find these instructions useful.

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

How to Write Really Good Documentation

Write a really bad manual and you’ll not only lose users, you’ll create ex-users who go out of their way to tell others how bad your application is. Documentation matters.

Forte, Brian. Red Hat Magazine (2007). Articles>Documentation>Writing>Technical Writing

How to Write Really Good Documentation: Donald Knuth Was Wrong

In the continuing absence of maturity in the software world, it’s the documentation that has to treat the tool-user with respect. Which is a further argument against Knuth’s Literate Programming. Since it’s all too common to see software toolmakers treat tool-users with short shrift, it’s a useful caution to have the ’software is written in one corner and documented in another’.

Forte, Brian. Red Hat Magazine (2007). Articles>Documentation>Writing>Technical Writing

How to Write Really Good Documentation: Four Rules and an Axiom

Keeping to the four rules articulated here—and never forgetting the axiom—will definitely improve your documentation. If nothing else, recognizing and observing these rules will raise the status of documentation and the people producing it. And they’ll use that raised status in at least two ways.

Forte, Brian. Red Hat Magazine (2007). Articles>Documentation>Writing>Technical Writing

How We Write: Putting the "Technical" in "Technical Writer"  

By becoming more technical, you can interact more efficiently with software developers and qualify for a greater variety of software documentation projects. This paper outlines ways to learn more about three prevalent technologies: programming languages, databases, and Web server technologies.

Owens, David. STC Proceedings (2004). Articles>Writing>Technical Writing

Hypertext as a Productivity Tool for Technical Writing  

Hypertext is a novel approach to computer-based information management based on associative indexing. The concept in general and the characteristics of typical systems are briefly reviewed. Strategies for applying hypertext techniques to the process of writing a technical document are examined. The way in which hypertext documents are used is discussed, focusing on a commonly encountered problem -- user disorientation within the document. Hypertext-based technical documents are compared and contrasted against their paper-based antecedents.

Lenarcic, John. STC Proceedings (1993). Articles>Information Design>Hypertext>Technical Writing

IBM User-Centered Design for the Documentation Designer  

The user-centered design of documentation is an aspect of product design that has often been under-emphasized. Difficulties inherent in documentation design include obtaining user, feedback to high-level design objectives; extracting user. feedback specific to a product’s documentation. rather than to the product as a whole; and managing the various resource constraints inherent in product development. IBM User-Centered Design offers a solution to these difficulties by employing a set of user feedback methodologies from which the documentation designer, a member of a multidisciplinary design team, extracts pertinent data to set design objectives and follow through to low-level designs.

Righi, Carol and Lynn VanDyke. STC Proceedings (1996). Articles>User Centered Design>Documentation>Technical Writing

Illustration and Language in Technical Communication    

Many technical documents present information both graphically and verbally. While much is known about the verbal tools of technical professionals, technical graphics have been less fully examined. Here the drawings of a United States patent are examined revealing a system for organizing and presenting visual information that is analogous to commonly-used models for organizing and presenting verbal information.

Donnell, Jeffrey. Journal of Technical Writing and Communication (2005). Articles>TC>Technical Writing>Technical Illustration

The Impact of Student Learning Outcomes Assessment on Technical and Professional Communication Programs    

Because of accreditation, budget, and accountability pressures at the institutional and program levels, technical and professional communication faculty are more than ever involved in assessment-based activities. Using assessment to identify a program's strengths and weaknesses allows faculty to work toward continuous improvement based on their articulation of learning and behavioral goals and outcomes for their graduates. This article describes the processes of program assessment based on pedagogical goals, pointing out options and opportunities that will lead to a meaningful and manageable experience for technical communication faculty, and concludes with a view of how the larger academic body of technical communication programs can benefit from such work. As ATTW members take a careful look at the state of the profession from the academic perspective, we can use assessment to further direct our programs to meet professional expectations and, far more importantly, to help us meet the needs of the well-educated technical communicator.

Allen, Jo. Technical Communication Quarterly (2004). Articles>Education>Assessment>Technical Writing

The Implications for Technical Writers of the Movement Toward Open Systems  

The movement toward open systems is gaining momentum. Those technical writers in the computer and software industries who have been accustomed to working in the world of proprietary systems will have to adjust to working in this new world of open systems. This paper briefly describes the open systems movement and then discusses in detail the implications of that movement for technical writers. This includes the challenges they will face and the skills they will need to develop. A brief case study of the involvement of technical writers in the Open Software Foundation’s DCE project is included.

Abbott, John J. STC Proceedings (1993). Articles>Knowledge Management>Open Source>Technical Writing

Implicature, Pragmatics, and Documentation: A Comparative Study    

This study investigates the link between the linguistic principles of implicature and pragmatics and software documentation. When implicatures are created in conversation or text, the listener or reader is required to fill in missing information not overtly stated. This information is usually filled in on the basis of previous knowledge or context. Pragmatics, the study of language use in context, is concerned with the situational aspects of language use that, among other things, directly affect implicatures required of the reader. I investigate how two manuals for the same software product can be analyzed on the basis of implicature and pragmatics. One is an original copy of the documentation that came with the product, the other an after-market manual. Results show that the aftermarket manual requires far fewer implicatures of the reader and does a better job of providing pragmatically helpful information for the user.

Wright, David. Journal of Technical Writing and Communication (2007). Articles>Documentation>Rhetoric>Technical Writing

Improving the Usability of Programming Publications  

This paper summarizes the work of a study group on ways to improve the usability of publications that support programming products. Task orientation, an approach to providing, organizing, and packaging information, is covered, together with innovations to improve the usability of programming publications: ease-of-use education, measurement of user opinion, and incorporating usability into the publications development process.

Bethke, W.M., P.H. Dean, E. Ort Kaiser and F.H. Pessin. IBM Systems Journal (1981). Articles>Documentation>Writing>Technical Writing

Improving Your Technical Document Writing Skills

Discusses the general technical writing process.

Doddihal, Vinayak. EditSphere (2008). Articles>Documentation>Writing>Technical Writing

Incorporating Human-Computer Interface (HCI) Technology Into the Technical Writer’s Role  

At last year’s STC corlference in Seattle, Dr. Donald Norman spoke about the technical writing community becoming an integral part qf the design/development team. The HCI certificate program qfered through Renesselaer Polytechnic Institute @PI,) provides information and teaches skills that enable the technical communicator to become a valuable part of that team. This paper discusses my experience incorporating what I learned in the HCI class on a work project.

Oakley, Joanne. STC Proceedings (1997). Articles>Education>Human Computer Interaction>Technical Writing

Indexing: A Step-By-Step Workshop  

This workshop presents a step-by-step methodology for producing thorough, usable indexes for technical documents. The methodology consists of these four steps: 1) Creating entries based on the material; 2) Creating entries based on users' questions; 3) Adding synonyms; and 4) Cross-referencing related entries. The workshop also includes hands-on exercises which illustrate the methodology and give participants a chance to practice using it.

Hash, Christine Milligan. STC Proceedings (1994). Articles>Indexing>Technical Writing

Information Architecture Concepts for the Technical Writer

Information Architecture (IA) as a discipline practiced by professionals in the information processing and development industry has many definitions and levels of understanding.

Gummaraju, Anupama. Indus (2005). Articles>Information Design>Writing>Technical Writing

Instructions for Giving Instructions: Creating Effective Documentation  

Increasingly technical communicators are being asked not only to write documentation and instructions, but to also teach subject matter experts how to write their own process explanations. While writing good documentation is an art, there are also formulas and templates that help guide effective process explanation. Whether instructions appear in written, verbal or digital formats, they should all observe basic conventions for graphics, layout, content organization, overviews, development of ideas, ample warnings and cautions, trouble shooting and tool lists.

Stern, Caroline M. STC Proceedings (2005). Articles>Documentation>Writing>Technical Writing

An Instructor Internship In Technical Writing

We cause ourselves problems by not knowing what our counterparts in industry are doing. In my case, I taught the textbook in my first business and technical writing courses at Indiana University East, Richmond.

Driggers, Stephen. ADE Bulletin (1986). Articles>Education>Writing>Technical Writing

An Introduction to API Documentation  

This session will help you to: identify relevant source of information; extract information from the source; create effective API documentation; create context-sensitive help for DLLs (Dynamic Link Library).

Dubey, Akash. STC India (2003). Articles>Documentation>SDK>Technical Writing

An Introduction to the Internet for Technical Writers  

In spite of all the news and excitement about the Internet, there are still millions of people who are not using it, including many STC members. Email and the ability to do Internet research are now required tools for technical writers. But where do you start when you want to “surf the Net”? What hardware do you need? How do you select an access route to the cyberspace? Once you’re on-line, where do you go? Here are some of the answers. Warning: the Internet changes rapidly. Some of these answers may not be valid by the time you are ready to go on-line.

Lenzo, Thomas J. STC Proceedings (1998). Articles>Internet>Writing>Technical Writing