Developing an Article from the Ground Up

Whether it's at the request of your company's powers-that-be or out of your own personal desire to spread your wings, you may be thinking about writing an article. It'll be easy enough. You're a writer, after all. You already know how to research topics, develop information, and create a coherent document. You've written tomes on the most arcane topics known to humankind. Surely one little 1000-word feature story is no big deal, right? That all depends. Article writing--for a specialized audience or for the general public--requires knowledge of a new process that many technical writers may not be familiar with. Fortunately, though, any professional writer can learn to transfer his or her existing skills to this new format, and you just might find the different method provides a mini vacation from your day-to-day work projects.

Chroust Ehmann, Lain. TECHWR-L (2001). Articles>Writing>Planning

Developing Indexes

As a technical writer, you'll typically have to create indexes for the print books and for online helps you develop. The type of index we mean here is the classic back-of-book index that shows page numbers on which topics and subtopics occur within the book. An online index is much the same except that you supply hypertext links rather than page numbers.

McMurrey, David A. Illuminati Online (2004). Articles>Editing>Indexing>Technical Writing

Developing Industrial Cases For Technical Writing on Campus  

At the World's Columbian Exposition of 1893, the World's Engineering Congress met and included special section, 'Division E, Engineering Education.' This division was the seed for The Society for the Promotion of Engineering Education, and one paper delivered in the section was 'Training of Students in Technical Literary Work,' evidencing early concern about engineers' education in technical writing. But concern alone did not solve the problem. Two decades later Edward D. Sabine, a terminal engineer, complained that most college graduated engineers could not even write a decent letter. And in the same year F. W. Springer, a professor of electrical engineering, spoke of the need for teaching 'engineering-English.' Fifty years ago Hale Sutherland, a professor of Civil Engineering, described how Case School of Applied Science had instituted a two-course, technical writing requirement to overcome 'the engineer's ancient weakness, his inability to speak and write effectively.' One approach to solving this problem has been cooperation. Seventy years ago C. W. Park wrote an article about the cooperative program at the University of Cincinnati, in which members of the Engineering and English Departments worked together to promote better writing; obviously the idea of teaming up is hardly new. Thirty years ago The Journal of Engineering Education published another description of a cooperative effort and just five years ago devoted an entire issue to technical writing. The need for teaching engineers to write and the difficulties in accomplishing the objective even cooperatively have been recognized for almost a century; we are still grappling with the problem.

Mair, David and John Radovich. JAC (1985). Articles>Education>Writing>Technical Writing

Developing Knowledge Base Articles

A short article that offers some tips on writing articles for a knowledge base, whether internal or client facing.

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

Developing the Specification for a Document

Between 25-30 percent of the overall writing time is typically devoted to developing the document specification, meaning how the document will be formatted and actually present the information. This is true even when the organization has a style guide with a prescribed format, but no “standard” for documentation overall. Although this may seem an inordinate amount of time and effort on the front end, before getting any information onto the paper, it is far more cost-effective than spending unplanned time rewriting and reformatting the document late in the production process.

Tech-Writer. Articles>Writing>Project Management>Technical Writing

Diagnosing and Curing Writer's Block Paralysis in the Workplace  

At one time or another, all writers--veterans or novices, technical or creative--struggle with writer's block. Advice on treating creative writer's block abounds, but very little information exists for technical writers who frequently must write even when they feel blocked. Fortunately, solutions used by creative writers to overcome blocks are often appropriate for technical writers in workplace situations. By understanding the symptoms, causes, and treatment of the problem, anyone can overcome and even prevent writer's block.

Ketelaar, Carolee C. STC Proceedings (1999). Articles>Writing

Dig for the Concrete and Specific

The good writer uses telling details, not only to inform but to persuade. Dig for the concrete and specific.

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

Dirty Battles in the Trench: Is It Wise to Use Real Materials for Editing in a Technical Writing Class?  

The use of real materials in a technical writing class involves both advantages and drawbacks. Use of real materials makes the class relate well to the work environment, improves self-esteem, critical thinking, and student motivation. Drawbacks include the problem of finding materials, a lack of course continuity, a lessening of use of the class text, and legal implications. Overall, the use of real materials for classroom editing is recommended.

Stibravy, John A. STC Proceedings (1993). Articles>Education>Writing>Technical Writing

Discovering That Writing for the Web is Different...Every Day, for the First Time

Every self-appointed pundit on the planet is saying that users are the new 'owners' of the online medium.

Usborne, Nick. Excess Voice (2007). Articles>Web Design>Writing

Discovering the Pedagogical Paradigm Shift in Technical Writing  

For my dissertation, I am analyzing technical writing textbooks from the early 1900s to the present to determine whether technical writing pedagogy has undergone or is undergoing a paradigm shift. When I began this study, my hypothesis was that technical writing pedagogy, like composition and rhetoric pedagogy, has shifted from the product orientation to the process orientation. Textbooks that are product oriented emphasize the study of examples or models, and textbooks that are process oriented emphasize the study of the writing process. Now that I have completed my study and am in the process of analyzing the results, my hypothesis is that technical writing pedagogy shifted from a product orientation to a combined product and process orientation.

Jeansonne, Jerold. STC Proceedings (1995). Articles>Education>Writing>Technical Writing

Distributed or Centralized: How to Maintain Quality When They Keep Reorganizing Your Organization  

Is there a 'best' way to organize technical publications? One central organization? Many small organizations per business unit? Communicators distributed through the development teams? Discuss the pros and cons of organizational structure and its relationship to quality.

Hackos, JoAnn T. STC Proceedings (1998). Articles>Writing>Quality>Technical Writing

Do Internet Users Want Deep Content or Immediate Gratification?

For a long time I have been an advocate of quality content on web sites. And now I am conducting an experiment that pitches quality content against immediate gratification.

Usborne, Nick. Excess Voice (2006). Articles>Information Design>Web Design>Writing

Do Technical Writers Need an International Standard for English-Language Spelling?

He demonstrates how ministers of state who speak different languages often choose English as the most convenient language of communication. He cites the 11-nation European Central Bank in Frankfurt as a typical organization that works only in English. And he notes that many of the journals published by respected international organizations such as the Pasteur Institute also are published in English. TC-Forum is another example.

Blicq, Ronald S. TC-FORUM (1999). Articles>Style Guides>International>Technical Writing

Do You Have the Brain to Be a Writer?

Are some people born to be great writers, or can they learn their way to greatness? An insightful survey of current thought on this age-old debate.

Zvalo, Peter. Writer's Block (1996). Articles>Writing

Boilerplate

The SMEs had a choice between two sets of tables they could use to input key product data. If their part of the project used items from the A list, they were supposed to use table A. If their part of the product used items from the B list, they were supposed to use table B. In almost every case, the SMEs used the wrong table, leaving gaps where their information did not conform to the columns of the tables.

Hewitt, John. Writer's Resource Center (2005). Articles>Writing>Technical Writing>SMEs

The Documentation Scene

Funny thing, documentation. Ought to be easy enough, surely? So why the disappointing results? What IS the elusive spark which distinguishes the professional author from others who put their hand to the pen (keyboard)?

Mobbs, John. ISTC (2002). Articles>Documentation>Writing>Technical Writing

Documentation Solutions for Complex Tools: Task-Based Design at the Cross Roads  

For most of the technical writing community, task-based documentation has become the panacea for presentation of end-product document (in any of its myriad forms including traditional linear manuals and online help). We believe, however, that applying this method to a complex tool, (for example, a software tool without a Graphical User Interface), challenges the task-based approach.

Swallow, Lisa and Matt Laney. STC Proceedings (2004). Articles>Documentation>Writing>Technical Writing

Documenting Contributory Expertise: The Value Added by Technical Communicators in Collaborative Writing Situations     

Technical communicators frequently collaborate in workplace projects and bring a host of different kinds of expertise to this collaboration. Yet the understanding of communicators’ expertise among managers and subject matter experts is grounded in a view of writing as a finished product and authorship as singular. This article documents many different kinds of 'contributory expertise' employed by writers collaborating to produce articles for publication. Expertise in research, textual composition, visual composition, as well as other kinds of expertise garnered on previous projects is often brought to collaborative projects. Often emerging and developing as a function of collaborative work is expertise in framing the project, conducting review processes, and assessing outcomes. These categories are discussed in some detail to provide practicing communicators with ideas for documenting expertise in their specific workplaces, to provide students with ideas for developing expertise in various areas, and to prov

Henry, James M. Technical Communication Online (1998). Articles>Writing>Collaboration>SMEs

Dodge the Grammar Traps

You don't have to swallow a grammar book to write correctly. If you can just avoid ten serious and very common traps, your chances of making a grammar mistake drop dramatically.

McAlpine, Rachel. Quality Web Content (2004). Articles>Writing>Grammar

Does Having a Blog Make You a Writer?  

For the techno-savvy TechRepublic member, writing in some form or fashion is an almost daily occurrence. But how effective is your communication? In this interview, author Barry Rosenberg shares his thoughts about the current state of technical writing skills.

Kaelin, Mark. TechRepublic (2005). Articles>Interviews>Technical Writing>Blogging

Doin' That Old Two-Step: A System for Getting Your Writing Right

Here's an awful question: "What is good writing?" When we run writing workshops for businesspeople, we often begin by asking for the characteristics of good writing versus bad writing. The first list typically contains words like simple, clear, accessible, concise, lively and conversational. The second list is on the flip side of the coin, with participants describing bad writing as complex, wordy, confusing, illogical, full of jargon and having no clear purpose.

Canavor, Natalie and Claire Meirowitz. Communication World Bulletin (2005). Articles>Business Communication>Writing

Don't Forget A Strategy for Microcontent—Headlines, Decks, Buttons and Links—When You Redesign Your Site

Little things mean a lot. Especially online. Microcontent—or the headlines, decks, subheads and other 'small' pieces of web copy—actually do most of the communicating on your web site. Handled poorly, microcontent can confuse and frustrate web visitors. Here's how to write microcontent to communicate to—instead of discombobulate—your readers.

Wylie, Ann. Communication World Bulletin (2004). Articles>Web Design>Writing>Metadata