Editing Your Own Documentation  

Technical writers sometimes fall into the trap of thinking that the user is stupid. I have often heard technical writers say things like 'well, if the user can't figure that out, maybe he’s in the wrong job!'

Docsymmetry (2003). Articles>Documentation>Editing>Technical Writing

Eleven Tips for Writing Incredibly Useful Procedures

Procedures are the meat and potatoes of technical writing. They help users get the job done. Follow these tips for writing clear and useful procedures that your users will appreciate.

HelpScribe (2008). Articles>Documentation>Policies and Procedures>Technical Writing

The Elves and the Shoemaker—We Don't Wear No Pointy Hats  

When technical communicators are part of a development team, we can do much more than write manuals. Our analysis and communications skills, user perspective can help launch a project team into productivity. We have a unique skill set which enhances the productivity and quality of the development process. By involving us early, we can assume technical communications tasks that developers otherwise perform. This exposure gives us a broader and deeper understanding of that which we communicate. Our involvement means better communication; with users and team members, and in deliverables and development processes.

Mazur, Sue and Jamie A. McCanless. STC Proceedings (1994). Articles>Documentation>Writing>Technical Writing

Excel Hacks for Help Writers

One of my earlier careers was in manufacturing management, and it grounded me in the principles of project planning and management. When I moved into technical communication, I brought my project management disciplines with me, and I embraced the prevailing tools of my new profession. I dutifully produced documentation plans in Microsoft Word and supported them with detailed project plans in Microsoft Project. However, the problem is that—like bad relationships—these artifacts never gave back results that were sufficient to reward the effort I put into creating them.

Hughes, Michael A. UXmatters (2008). Articles>Documentation>Technical Writing>Microsoft Excel

The First Line of Support

Customer support costs account for as much as 60 percent of a high-tech company’s total costs. Documentation is the first line of support for most customers, and customers usually use documentation to find the answer to a problem they’re having. The inevitable result of poor or nonexistent documentation is that more people try calling the customer support lines for help.

Butow, Eric. Software Development Times (2006). Articles>Documentation>Software>Technical Writing

Getting to Expert

The gaps in your documentation aren’t there because you haven’t consider a particular level of user; the gaps in your documentation are there because you haven’t considered how one level of user becomes another. How DO you get from Beginner to Expert?

McLean, Gordon. One Man Writes (2008). Articles>Documentation>User Centered Design>Technical Writing

Guidelines for Writing Technical Documentation for an International Audience  

A guide to help technical writers in all countries who have to write English-language technical documentation for products that will be sold worldwide.

tekom (2003). Articles>Documentation>International>Technical Writing

Hidden Factors of Documentation Quality -- Part 1

The first impulse of many documenters is to turn our work over to editors and graphic designers, or to form committees and develop style guidelines. All of these measures are useful, but none can assure us of quality when there are basic problems with the way we go about producing documentation.

Sesnovich, Bruce A. Boston Broadside (1993). Articles>Documentation>Quality>Technical Writing

The Hidden Power of the Online Manual

Writing software manuals is boring, isn't it? We often think, "My software is easy to use. The user interface is intuitive. Why should I waste so much time writing documentation which nobody will read anyway?" Sometimes it's true. I've never read the WinZip or Internet Explorer manuals. Everything seems clear enough without further explanation. Nevertheless, even if your manual isn't being helpful to your software users, it may be helpful to you. Publish your manual online and turn its hidden power into a real benefit for your business.

Crane, Dennis. Dr. Explain (2006). Articles>Documentation>Online>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

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

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

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

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

Instructions: Write for Busy, Grouchy People

People hate reading instructions, and will only glance at them when they are hopelessly lost. By then, they will already be frusrated and behind schedule. Organize your instructions carefully, phrase them clearly, and make them as brief as you possibly can.

Jerz, Dennis G. Seton Hill University (2000). Articles>Documentation>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

Introduction to Writing Software Documentation

Documentation is a vital but often unappreciated part of almost every software product. Most software documentation is written by technical writers, employees who specialize in the field. People not in the field often fail to appreciate just how complex the process of writing documentation really is and how dependent it is on developers and other software professionals. There's also a lot of confusion out there about just what technical writing encompasses.

Karin, Janice. Suite101. Articles>Documentation>Writing>Technical Writing

Is Your Website Poised to Deal With Its Growth?  

Every webmaster nourishes the dream that his or her website will make it the big way. This is very much human because people carry out any task in ardent hope. What is more human out here is that earthy fellows like us base our aspirations more on speculation rather than specific set of steps undertaken to bring the dream a bit closer to reality. And this is not all, particularly in case of growth of a site which brings newer problems in the wake of its growth. It cannot be disputed that you can probably get some good web hosting on economy price. But if you expect top of the line service on this price, acknowedge gracefully that your are just asking for the moon. Probably you are not catching up with wisdom that business needs decisive investments.

Azam, Rahbre. Amateur Writerz (2008). Articles>Documentation>Web Design>Technical Writing

The Issue of Quality in Professional Documentation: How Can Academia Make More of a Difference?      

This article recommends strategies academics can use to contribute to an issue of great interest in industry: how best to define, measure, and achieve quality documentation.  These strategies include contextualizing quality definitions, advocating the use of multiple quality measures, conducting research to identify specific heuristics for defining and measuring quality in particular workplace contexts, and partnering with industry to educate upper management about those heuristics and the benefits of promoting technical communicators to the strategic role of organizational “gatekeepers of quality.”

Spilka, Rachel. Technical Communication Quarterly (2000). Articles>Documentation>Collaboration>Technical Writing

Just the FAQs  

Offers advice on creating effective FAQ documents.

Hart, Geoffrey J.S. Intercom (2004). Articles>Documentation>Technical Writing>FAQ