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

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

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

The Keys to Clarity, Consistency, and Correctness

How can you make documentation more clear, consistent, and correct for your users? Following are some guidelines I find effective when documenting concepts and organizing documents.

Hassell-Corbiell, Rives. Indus (2002). Articles>Documentation>Writing>Technical Writing

Life: A User's Manual

With his back towards the reader, a bucket over his head, hands and feet tied up by SGML, CALS and company standards, and half choked by all the possibilities of the latest computer system the writer tries to produce manuals and instruction books for unsuspecting readers!

Forsslund, Lars. TC-FORUM (1998). Articles>Documentation>Writing>Technical Writing

Making Documentation Accessible to Users With Disabilities  

Good documentation takes into account the needs of people with disabilities. Such documentation is termed 'accessible' and provides support for the assistive technologies used by people with disabilities. For example, accessible documentation provides a text equivalent for each graphic element, such as a picture, flow diagram, or icon. This provision is necessary for users who rely on screen readers to read the documentation.

Chappell, Gail B. STC Proceedings (2003). Articles>Documentation>Accessibility>Technical Writing

Making Product Information an Integral Part of the Development Process  

Document inspections formalize the document review process and encourage the full participation of technical developers in the documentation development process. A document inspection consists of three parts: a briefing meeting, a desk review, and a recording meeting. At the briefing meeting, you state your requirements for the inspection process. During the desk review, the technical developers review your document. At the recording meeting, you review the comments made by the technical developers, and as a group decide on appropriate resolutions.

Hildebrand-Lund, Ruth. STC Proceedings (1996). Articles>Documentation>Workflow>Technical Writing

Making Sense of Step-by-Step Procedures    

Procedural instructions that consist of only a sequence of steps will probably be executable, but nevertheless 'meaningless' to users of technical devices. This paper discusses three features that can make procedural instructions more meaningful: adding functional coordinating information, adding information about the use of the technical device in real life, and adding operational information about how the device works. The research literature supports the effectiveness of the first feature, but offers little evidence that real life elements enhance understanding of instructions. As for operational information, the research suggests that users are willing to read it, and that it contributes to better understanding and performance in the long term, but only if it is closely related to the procedure. As a conclusion, we propose a theoretical framework that assumes three levels of mental representation of instructions: syntactical, semantic, and situational.

Steehouder, Michael F., Joyce Karreman and Nicole Ummelen. ACM SIGDOC (2000). Articles>Documentation>Rhetoric>Technical Writing

Managing the TWI Mailing List: As Tough as it Gets

The success or failure of any mailing list depends entirely on its members - as in how effectively can they contribute on the list or how diligently can they enhance the quality of ongoing discussions. If you watch closely, the level of discussions combined with the maturity of posters is what characterizes these mailing lists to a large extent. For instance, take a firsthand look at Technical Writers India mailing list or TWI, as it is popularly called.

Prabhakar, Rahul. Blogspot (2006). Articles>Documentation>Technical Writing

Meaningful Microcontent

Microcontent refers to small, granular, and possibly representative (that can provide a summary of or a navigation to a larger set of information) bits of information, typically available on the Web. An example in the domain of journalism might be headlines and news summaries, small bits of content that can be used on a front page of the news with links to more in-depth articles. The definition has grown in scope as much as in its application.

Albing, Bill. KeyContent.org (2006). Articles>Documentation>Content Management>Technical Writing