Software Documentation Process: Symbios Logic  

This panel presents the software documentation processes of three companies. Participating on an interface design team allows writers to contribute to a software’s usability and to develop supporting documentation early in the software’s development cycle. This presentation summarizes the crossfunctional team’s process and strategies for designing the interface and for preparing usable support products. I will also review the successes and problems we encountered as we created online help and a printed user guide. Writers can learn about Symbios Logic’s interface design team as one approach to creating usable software with accurate, quality documentation. At Symbios Logic, one of our goals is to develop data storage products supported by accurate, easy-to-use documentation. The major challenge we face in completing this documentation is meeting the release dates for our products. To achieve this goal, we are re-designing our latest software by combining both interface and documentation development into one design process.

Burroughs, Dia H. STC Proceedings (1996). Articles>Documentation>Writing>Technical Writing

Some Advice on Writing a Technical Report

The Technical Report (TR) is a common written form through which computer scientist communicate their findings. Each TR should have a focused topic that is developed logically along some clearly identified perspective. The major components of a TR are title, author information, date, keywords, informative abstract, body, acknowledgments, references, and appendices. Typically, the body is organized into four sections: motivation, methods, results, and discussion. This document offers advice and specifications for writing TRs.

Sherman, Alan T. UMBC (1996). Articles>Writing>Reports>Technical Writing

Some Advice on Writing a Technical Report

The Technical Report (TR) is a common written form through which computer scientist communicate their findings. Each TR should have a focused topic that is developed logically along some clearly identified perspective. The major components of a TR are title, author information, date, keywords, informative abstract, body, acknowledgments, references, and appendices. Typically, the body is organized into four sections: motivation, methods, results, and discussion. This document offers advice and specifications for writing TRs.

Sherman, Alan T. UMBC (1996). Articles>Writing>Reports>Technical Writing

Starting with the Vendor's Documentation  

When a company purchases software for in-house implementation technical writers can contribute to the implementation and training by customizing the vendor’s documentation. This paper describes three strategies with case histories: rewrite; revise and expand; supplement. It offers hours-per-page statistics for comparison and outlines a method of analyzing how much to invest in additional documentation. This paper focuses on user’s guides, but the logic also applies to training guides and on-line help.

Littlewood, Ann P. STC Proceedings (1995). Articles>Documentation>Writing>Technical Writing

Strategies for Teaching Online Documentation    

This workshop outlines the rationale for teaching college courses in online documentation, issues to consider, suggests a strategy for teaching the course (including topic sequence, exercises, and simulation), and demonstrates useful electronic resources.

Sammons, Martha C., Tabatha Dillon and Melinda Hoffbauer. STC Proceedings (1999). Articles>Education>Writing>Technical Writing

Strategies for Winning Recognition: Building a Visible, Viable, and Valuable Documentation Team  

Technical writing teams can improve their standing within their organizations. The purpose of this presentation is to share our experiences at Mirant where we've achieved recognition and respect as a vital internal service to the IT department and, increasingly, to the rest of the company.

Harkness, Holly E. STC Proceedings (2003). Articles>Documentation>Collaboration>Technical Writing

A Structured Process for Transforming Usability Data into Usability Information  

Much research has been devoted to developing usability evaluation methods that are used in evaluating interaction designs. More recently, however, research has shifted away from evaluation methods and comparisons of evaluation methods to issues of how to use the raw usability data generated by these methods. Associated with this focus is the assumption that the transformation of the raw usability data into usability information is relatively straightforward. We would argue that this assumption is incorrect, especially for novice usability practitioners. In this article, we present a structured process for transforming raw usability data into usability information that is based on a new way of thinking about usability problem data. The results of a study of this structured process indicate that it helps improve the effectiveness of novice usability practitioners.

Howarth, Jonathan, Terence S. Andre and Rex Hartson. Journal of Usability Studies (2007). Articles>Usability>Reports>Technical Writing

A Style in Technical Writing   

This course is designed to teach you to: recognize the variety and characteristics of styles of technical communication; adapt your writing style for different aims and audiences; revise efficiently and appropriately; and articulate reasons for revisions in your writing.

Dragga, Sam. Texas Tech University (2009). Articles>Information Design>Visual>Technical Writing

Style That Economizes Mental Energy  

Perhaps the most important feature of good writing style for scientific and technical communication is economy: writing that reduces the mental labor of the reader or user. I describe the principle of "conservation of mental energy" as developed by Herbert Spencer and extended by later studies in readability and psycholinguistics. Stylistic techniques that make reading easier have powerful application to the prose crafting that sci/tech communicators do every day. The idea of conserving mental energy, or being "efficient" in communication, gives us a touchstone for thinking about good style and a rationale for explaining why it's valuable.

Hirst, Russel. STC Proceedings (2004). Articles>Writing>Technical Writing>Minimalism

Succeeding as a Technical Writer

A list of rules that have served me in good stead over my entire career.

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

A Survey of Technical Writing Practitioners and Professors: Are We on the Same Page?   

Do technical writing professors teach what practitioners practice? Do practitioners practice what professors preach? We surveyed writers and teachers nationwide, asking each group to rate the importance of types of writing, writing skills, electronic communications, computer usage, and nonwriting topics, such as oral presentations and graphics. Teachers and writers agree that ethics, revision, and document design are important. However, writers focus on manuals, whereas professors teach reports and resumes. Writers emphasize grammar, punctuation, hypertext, and total quality management, whereas teachers emphasize passive voice and personalization. The two groups differ often and significantly.

Gerson, Sharon J. and Steven M. Gerson. STC Proceedings (1995). Articles>Education>Writing>Technical Writing

Taking Advantage of Reflexive Responses

None of us likes to admit that we have conditioned reflexes that override our higher cognitive abilities, yet such denials notwithstanding, each of us does occasionally respond without thinking something through clearly. As technical communicators, it's important for us to accept this fact of human nature and plan for it in our documentation, and to work with the developers of the products that we document to both take advantage of the helpful reflexes and find ways to ward off the harmful ones.

Hart, Geoffrey J.S. Geoff-Hart.com (2001). Articles>Documentation>Writing>Technical Writing

A Tale of Two Technical Writing Teams  

Sometimes considered an afterthought in the product development lifecycle, technical writers often struggle to become part of a performing Agile team.

Broderick, Stacia. Rally Software Development (2007). Articles>Project Management>Agile>Technical Writing

Teaching Business and Technical Writing in China: Confronting Assumptions and Practices at Home and Abroad    

In light of growing interest in technical communication around the world, cross-cultural teaching opportunities may challenge basic assumptions about teaching and learning for both teachers and students. A faculty-development project in the People's Republic of China illustrates various ways facilities, educational practices, and worldviews from each side of the exchange require significant compromise. A negotiated, student-centered classroom environment may be a significant strategy for instruction in such settings.

Dautermann, Jennie. Technical Communication Quarterly (2005). Articles>Education>Technical Writing>China

Teaching Critical Thinking in The Technical Writing Class  

It is probable that the Technical Writing course provides for upperclassmen the most intensive and extensive experience with written English that they will have during their undergraduate education. Traditionally, the course has bridged the world of work and the world of school. We instructors try to prepare our students for on-the-job professional writing, and it would seem that this objective is met through the special goals of the course: writing to particular audiences, using precise language, mastering formats, and using graphics. Such observable skills are valuable: indeed, Green and Nolan indicate, in their piece in the recent 'Education' issue of Technical Communication, that the fundamental requirements of an entering technical communicator's job are writing, editing, and researching. Yet, what are we to make of the prediction that Paul V. Anderson cites in that very same issue, that the advent of more highly sophisticated computer software will eliminate up to 75 percent of the present jobs in technical communication, rendering entire categories of jobs obsolete? We must teach, then, in addition to these surface writing abilities the deep structure reasoning skills that nourish them, those skills that are highly esteemed by business, industry, and academia.

Meyers, G. Douglas. JAC (1985). Articles>Education>Writing>Technical Writing

Teaching Documentation Writing: What Else Students--and Instructors--Should Know    

Discusses knowledge, problem-solving strategies, and desktop publishing skills students need to learn about documentation writing. Describes a course that provides these skills. Also applies to in-house training programs.

Boiarsky, Carolyn and Michael Dobberstein. Technical Communication Online (2003). Articles>Education>Documentation>Technical Writing

Teaching Engineering Communication: A Novel Vertically-Integrated and Discipline-Conscious Curriculum  

The demands of former students, of industry, and of the accreditation board have prompted the engineering education community to investigate the integration of communication proficiencies into the four-year engineering curriculum. While much literature has been devoted to this task in the last several years, the engineering communication programs at most institutions can be described as employing either a peripheral or diffuse model to offer technical communication instruction. Each of these models is problematic. This article describes a novel 'hybrid' engineering communication education model under development at NC State University that is vertically integrated and discipline conscious.

Kmiec, David M., Jr. STC Proceedings (2004). Articles>Education>Technical Writing>Education

Teaching Technical Writers to Be Anthropologists  

Ethnographic research, traditionally conducted by academic researchers, yields valuable knowledge on the ways in which workplace cultures and technical communication interrelate. This paper describes an MA course in which practicing technical writers composed workplace ethnographies with a focus on writing and reading processes. Conclusions outline the value of such research for individual technical communicators, for their employers, for the discipline of technical communication, and for the profession.

Henry, James M. STC Proceedings (1995). Articles>Writing>Technical Writing

Teaching Technical Writing Through Student Peer-Evaluation    

Individual students in two different sections of an undergraduate civil engineering laboratory were tasked with preparing three professional-quality laboratory reports. The teaching assistant and/or instructor used established criteria to grade the first two reports prepared by students in one section. The first two reports prepared by students in the other section were peer evaluated by assigned fellow students within the same laboratory section using identical grading criteria. The peer evaluated section had a higher class average than the teaching assistant/instructor graded section on the fist two reports. The third report prepared by students from both sections was graded by a professional educator/architect without knowledge of a student's class section. The peer evaluation students also had a higher class average on the third report, suggesting that the peer evaluation process may have positively contributed to those students' writing skills.

Jensen, Wayne and Bruce Fischer. Journal of Technical Writing and Communication (2005). Articles>Education>Technical Writing>Collaboration

Teaching Web Design in the Technical Writing Service Course: Steps Toward a Planned Evolution  

This study uses an online survey of technical communication educators to examine trends in the technical writing service course with regard to web design. Participants for the study were representatives of programs in technical communication in four-year institutions of higher education throughout the United States. The study contributes to research into the function of the technical writing service course in the current technological climate. Identifying trends is one component in an evaluation that will aid effective evolution of this significant course.

Brewer, Pam Estes. STC Proceedings (2004). Articles>Education>Web Design>Technical Writing

The Team Approach to Writing Policies and Procedures  

Although many companies claim to have working teams within their corporate structure, it may be difficult to use the same approach for writing documentation. With the demands for controlled documentation to meet quality standards, involvement in policy/procedure writing is an important factor in developing a sense of ownership and commitment to maintaining a document control system. A team approach to writing procedures may involve more time, but the results are operations consensus, improved writing skills, and a boost of professional confidence.

Whitmer, Diane L. STC Proceedings (1996). Articles>Documentation>Technical Writing>Collaboration

Tech Writers, Grammar, and the Prescriptive Attitude

Prescriptive grammar is useful for teaching English as a second language, but it has little value for the practicing writer. Clinging to it may provide emotional security, but only at the expense of making writing harder than it needs to be. The culture-wide devotion to it will not be changed in a moment. But conscientious writers can at least change their own habits, and make life easier for themselves.

Byfield, Bruce. TECHWR-L (2008). Articles>Writing>Editing>Technical Writing

Tech Writing 2.0: Special Report on New Trends in User Documentation

This report outlines the developments in what many are calling "Web 2.0" and the impact that these developments may have on technical and user documentation. We've called these trends "Tech Writing 2.0". Tech Writing 2.0 promises a new means of communication that business can use to promote and support their products and services. This means that the nature of technical communication will change.

Pratt, Ellis. Cherryleaf (2006). Articles>Writing>Technical Writing>User Centered Design

Tech Writing: It's More Than Just Computers

We rarely recognize that the manual that tries to explain how to assemble the new desk also falls under the broad definition of technical writing.

About.com (2005). Articles>Writing>Technical Writing