How to Write Effective Text

It doesn't matter how dazzling your Web site looks if you don't have good, clear copy that appeals to your readers' basic desires--and is easy to read.

Will-Harris, Daniel. EFuse (2004). Articles>Writing>Rhetoric

How to Write for an Overwritten World

Have you noticed that everyone is a writer these days? Besides all the people who want to publish books, from heads of corporations to bloggers to people who've had tough lives, the digital revolution gives us professionals of every kind issuing their own e-newsletters, vendors deluging us with e-mail messages, and virtually everyone creating web sites and blogs.

Canavor, Natalie and Claire Meirowitz. Communication World Bulletin (2006). Articles>Writing>Professionalism

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 To Write Well

The phrase 'Plain English' (although widely used) is a little misleading. It is nothing to do with the English language as such. The principles outlined here apply to writing in any language. A more accurate expression is 'plain language'.

Ziska Designs (2003). Articles>Writing>Rhetoric>Minimalism

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

The Humble Hyphen

The hyphen serves a single function. It joins things together: syllables of a word separated at the end of a line; two words used as a compound; or a modifier and the word it describes (when the combination itself is used as a modifier). But for the latter two functions, a hyphen isn't always needed. So how do you decide?

Wenger, Andrea. Carolina Communique (2006). Articles>Writing>Grammar

Humor, Credibility, and International Online Exchanges  

St. Amant examines the problematic effects of humor on international online communication.

St. Amant, Kirk R. Intercom (2001). Articles>Writing>International

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

The Idea is the Message  

Scientific communication differs from technical communication in several ways. One is that scientific communicators work with ideas rather than with a product. They present data and the inferences and conclusions drawn from those data. The information or the idea is the message. Scientific editors facilitate the transfer of knowledge from authors to readers.

Burgan, Murrie W. STC Proceedings (1995). Articles>Scientific Communication>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

Imagining the Blogosphere: An Introduction to the Imagined Community of Instant Publishing

Blogs above the waterline—those which are frequently updated, widely read, and consistently linked—may represent the conception of blogs in the public mind, but they are not representative of blogs in general.

Lampa, Graham. Into the Blogosphere (2004). Articles>Writing>Community Building>Blogging

The Impact of EQ Training on Collaborative Professional Writing  

Over the course of each semester, students in 300-level business communication courses can expect to produce a number of various types of messages and reports with emphasis on the psychological development of the message. Although education has traditionally demanded an individual approach to most writing tasks in order to assess student performance, most practitioners in the field of business communication recognize the importance of collaborative writing as a necessary skill in preparing students to enter the job market where teams rather than individuals are the primary work unit.

Sigmar, Lucia S., Tab W. Cooper, Geraldine E. Hynes and Kathy L. Hill. Association for Business Communication (2008). Articles>Writing>Education>Business Communication

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

The Importance of Audience

Clear writing is essential if you want your message to get across clearly to your audience. But, what makes your writing clear will vary and is ultimately dependent on your target audience. Before you write, know who you are writing for.

WordsWork. Articles>Writing>Audience Analysis>Rhetoric

Improved Student Writing in Business Communication Classes: Strategies For Teaching And Evaluation    

Students in business communication classes are expected to write various types of documents. Research has illustrated that undergraduate student writing skills have not improved even though most states have begun writing proficiency tests at the elementary, middle, and high school levels. By the time students enroll in college, students are expected to be proficient writers. In some cases, this is true. In far too many cases, students continue to need writing development. In business communication classes, these weaknesses cannot be ignored. This article's purpose is to give guidance to instructors to motivate their students to produce better written products. The difficulty is how to do this most effectively. The authors present some ideas on how to improve student writing through some creative teaching and evaluation strategies.

Stowers, Robert H. and Randolph T. Barker. Journal of Technical Writing and Communication (2003). Articles>Education>Business Communication>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

Including Purpose in Software Documentation  

Argues that technical writers should include a discussion of the purpose behind every procedure described in software documentation.

Block, Barbara M. Intercom (2001). Articles>Documentation>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