Avoid the SOX (Sarbanes-Oxley) Documentation Nightmare With These Five Tips

The Sarbanes-Oxley Act has been called the most comprehensive reform of corporate law since the Securities Exchange Act was passed in 1934. The effects of SOX are far reaching. Its provisions govern actions by management, audit committees, and boards of directors of public companies. Like it or not, Sarbanes-Oxley is here to stay. Its impact on IT departments is major and growing. The reaction of many IT groups is to document everything in sight in an attempt to cover themselves. In the end, this can be counter-productive, expensive and wasteful.

D'Amico, Vin. IT World Canada (2006). Articles>Documentation>Regulatory Writing

Avoiding Traumatic XML/SGML Transitions: Moving to XML/SGML Without Losing Your Writers Along the Way  

When moving to single-sourcing through XML and SGML, management often spends considerable time on tools evaluation and content management, but not enough on preparing the writers for the paradigm shift to the new environment. This presentation provides some hints for a successful transition for your personnel as well as your documentation.

Gelb, Janice. STC Proceedings (2003). Articles>Writing>XML>Technical Writing

Baby Steps To Writing Success

After a lifetime's worth of writing, I can file these baby steps under the 'wish I'd known when I started' category. They're vital. If you follow them, not only will you be successful at writing at some time in the future, you'll be successful right now.

Booth, Angela. Digital-E (2003). Articles>Writing

Back Off or Show Off

When the news or topic is most serious, understate. When the topic is least serious, exaggerate.

Clark, Roy Peter. Poynter Online (2004). Articles>Writing>Journalism

Back to the Future: Instructional Practices and Discourse Values    

When I think of writing-across-the curriculum—especially when asked to look toward the future, I am drawn to looking back to my initial involvement in WAC in the mid-1970's.

Herrington, Anne J. LLAD (1997). Articles>Language>Writing Across the Curriculum

Banned from Other Blog Sites

Freedom of expression is not ruling the blogosphere, because insecure bloggers will block your attempt to post comments, or even read their blog, should they decide you are "too controversial" or "too different from me". Opinionated blogs are the worst culprits of cowardly post blocking.

Streight, Steven. Blogger.com (2004). Articles>Web Design>Writing>Blogging

Baselining Documentation on a Wiki

The dynamic nature of wikis can cause a few headaches when you need to baseline documentation that's on a wiki to correspond with the release of your product. This blog post looks at some ways in which you can try baselining wiki content.

DMN Communications (2008). Articles>Documentation>Technical Writing>Wikis

The Basics of Book Profits

Most writers have no idea how much money they can expect when their book is published. The formular, however, is fairly straightforward. To begin with, a writer generally receives an advance. An advance is payment, in advance, based on the expected initial earnings of the book. Royalties (ranging from 4% to 8% in most cases) are generally based on the cover price of the book, but that does not include books that are discounted or remaindered. So, for the sake of argument, say you sold 20,000 full-price copies of a paperback priced at $7 (I know it would more likely be $6.95 but I am going to use round numbers.) If your royalty percentage were a generous 8% you would make a total of $11,200.

Hewitt, John. Writer's Resource Center (2004). Articles>Writing>Publishing>Writing

The Basics of Quality  

With constantly changing deadlines and last minute major revisions, how can technical writers ever hope to create quality documents? Members of the STC Quality Special Interest Group (SIG) will present some basic concepts that will provide insights into ways you can improve the quality of your documentation. They will look at what is meant by 'quality documentation', how documentation quality can be measured, how quality can be implemented in documentation processes, how ISO 9000 requirements can be adapted to help improve the documentation process, and how the relationship between developers and writers can impact documentation quality.

Rupel, Roberta A., Lori H. Fisher, Donald S. Lenk, Ralph E. Robinson and Richard Colvin. STC Proceedings (1999). Articles>Writing>Quality>Technical Writing

Battlecat Then, Battlecat Now: Temporal Shifts, Hyperlinking and Database Subjectivities

Like all media forms, the blog is not transparent. The technological code of the software contains affordances that filter and, in part, determine the constitution of the private/public Self represented in any weblog. And so, what kind of Self (or Selves) are made possible or enabled by typical blogging practice?

Jarrett, Kylie. Into the Blogosphere (2004). Articles>Web Design>Writing>Blogging

Be An Author, Not a Writer: Breaking Into Retail-Market Computer Book Publishing  

Many experienced technical communicators already have the skills and experience required to be successful authors of retail-market computer books. What they generally lack, however, is an understanding of the retail computer book publishing industry: the roles of the various players, options and techniques for landing that all-important first contract, navigating the ins and outs of money and contracts, developing book proposals, and working on their own. By learning more about the industry, technical communicators gain two things: an increased chance of becoming a first-time author and, more importantly, whether this is an appropriate career choice for them.

Benz, Christopher J. and Michelle Corbin Nichols. STC Proceedings (1998). Articles>Writing>Publishing

Be Concise

When giving overview information, be concise. Save the details and flowing language for those that want them or have the time, but don't slow down the skimmer. This doesn't mean skip the details, just keep them from people who don't need them.

Bricklin, Dan. Good Documents (1998). Articles>Writing>Workplace>Technical Writing

Be Succinct! (Writing for the Web)

The three main guidelines for writing for the Web are: be succinct: write no more than 50% of the text you would have used in a hardcopy publication; write for scannability: don't require users to read long continuous blocks of text; use hypertext to split up long information into multiple pages.

Nielsen, Jakob. Alertbox (1997). Articles>Web Design>Writing

Becoming a Journal Author   

This session will help participants understand how to write and submit a manuscript for publication in Technical Communication. It covers the types of articles the journal publishes, its audience, and suggestions for choosing topics, doing research, and preparing a manuscript.

Hayhoe, George F. STC Proceedings (1999). Articles>Writing>Publishing

Being Personal isn't About Being Their "Buddy"

I have written often about the value of writing online in a personal voice. In particular, emails and newsletters lend themselves to a genuine, personal tone.

Usborne, Nick. Excess Voice (2004). Articles>Collaboration>Writing>Technical Writing

Benefits of Using a Professional to Write User Documentation

Studies have shown organisations value the following benefits: overall organisation, the sales team, and documentation meets the customer's requirements.

Cherryleaf (2003). Articles>Writing>Professionalism>Documentation

Betriebsanleitungen für Anlagen  

Der Normenunterausschuss NATG-F des Deutschen Instituts für Normung e.V. ist derzeit damit befasst, Regeln zur Erstellung von Betriebsanleitungen für Anlagen zu erarbeiten.

Doculine (2002). (German) Articles>Documentation>Writing>Technical Writing

Better Readability for Improving the Number of Site Viewers

Web content readability is an often underestimated aspect for a web site. There are design rules for designers to follow, and there are SEO tips and tricks for SEO experts to use. But this is not all. Though beautiful designs and search engine optimization are extremely important, there are also other issues that a web marketer needs to consider in order to run the site successfully. Readability is one of them.

Stoyanova, Tsvetanka. SEOchat (2005). Articles>Web Design>Writing>Search

Beware of Adverbs

Beware of adverbs. They can dilute the meaning of the verb or repeat it.

Clark, Roy Peter. Poynter Online (2004). Articles>Writing>Diction>Rhetoric

Beware: Generic Words Can Indeed Be Trademarked

In article by Sabra Chartrand in the New York Times (March 13, 1995), makes it clear that the name of electronic products — books, photos, music, and titles — can be a bone of contention. Did you know that the Microsoft Corporation owns the rights to use the word bookshelf as applied to any CD-ROM product? In 1991, the software giant trademarked the term to cover its collection of reference books, Microsoft Bookshelf.

Editorial Eye, The (2003). Articles>Intellectual Property>Trademark>Writing

Beyond Internationalization: Multicultural Education in the Professional Writing Contact Zone    

To bridge the gap between composition and professional communication studies, we should add multiculturalism to the widely accepted international perspective in professional communication instruction, thus transforming the classroom into a contact zone (Pratt). The practical necessity of intercultural communication in a global marketplace necessitates internationalization. The international perspective, accounting for the heterogeneity of the technical communication audience, focuses on audience analysis and leads us to encourage students to learn about the multiple, cultural layers of audience. A multicultural perspective, however, can teach students of professional communication about the complex relationship between language and ideology and the underlying forces that shape and reflect the ways we use language. Multiculturalism's critical component provides insights into the structures and ideologies of domination/subordination and provides students with the linguistic, intellectual, and moral tools for resisting fear and prejudices. Likewise, the international perspective in professional communication can inform issues of audience analysis in composition.

Grobman, Laurie. Journal of Business and Technical Communication (1999). Articles>Education>Writing>Technical Writing

Beyond Plagiarism: Ethical Issues in the Technical Communication Classroom   

Recent discussions of ethical issues that relate to technical communicators reflect the rise of interest in this topic. Although some journal articles do look at teaching ethics in the technical communication classroom, most concentrate on ethics in the workplace. Yet, for students to understand current and future ethical issues, we must heighten their awareness of potential problems before they encounter such problems in industry and business situations.

Horowitz, Renee B. STC Proceedings (1994). Articles>Writing>Ethics>Plagiarism

Beyond the Mechanical: Technical Writing Revisited  

Optimism about the future of technical writing can be sustained only if we persist in setting for technical writing the same standards we apply to other sophisticated modes of writing and require refinement in style as well as accuracy in content. The importance of content in technical writing, of the information presented, may seduce us into seeing technical writing as purely a form of language engineering and into teaching our students to perform mechanical writing tasks, churning out dull reports to fit mindlessly into the institutional norms of industry and government.

Iyasere, Marla Mudar. JAC (1988). Articles>Writing>TC>Technical Writing

"Big Picture People Rarely Become Historians": Genre Systems and the Contradictions of General Education

This study synthesizes Y. Engeström's version of cultural historical activity theory and North American genre systems theory to explore the problem of specialized discourses in activities that involve non-specialists, in this case students in a university 'general education' course in Irish history struggling to write the genres of professional academic history. We trace the textual pathways (genre systems) that mediate between the activity systems (and motives) of specialist teachers and the activity systems (and motives) of non-specialist students. Specifically, we argue that the specialist/lay contradiction in U.S. general education is embedded in historical practices in the modern university, and manifested in alienation that students often experience through the writing requirements in general education courses. This historical contradiction also makes it difficult for instructors to make writing meaningful for non-specialists and go beyond fact-based, rote instruction to mediate higher-order learning through writing. However, our analysis of the Irish History course suggests this alienation may be overcome when students, with the help of their instructors, see the textual pathways (genre systems) of specialist discourse leading to useful knowledge/skill in their activity systems beyond the course as specialists in other fields or as citizens.

Russell, David R. and Arturo Yanez. WAC Clearinghouse (2002). Articles>Writing>Rhetoric