Articles

Glossary of technical writing terminology

Language

Glossaries aid clarity shows the benefits of including a glossary in a technical document.

Copywriting and technical writing compared explains some fundamental differences in the language used in these two forms of communication.

Beyond Plain English shows how ASD Simplified Technical English™ provides a rigorous framework for writing clear English.

Writing for an international audience describes some of the issues that arise when documentation written in English is produced for an international market.

Eliminating unnecessary words shows how to reduce the number of words in a text.

Document design

Alternatives to software documentation itemises alternative approaches to helping people use software.

FAQs: do better solutions exist? shows why 'frequently asked questions' are not a good method of helping people to find answers to their questions.

Users' documentation preferences summarises readers' preferences and the way they use documentation.

Usability, testing and documentation discusses the relationships between these three areas of product development.

Information Mapping is a proprietary methodology for the design of documentation.

Indexing technical documents explains why it is necessary to have an index, even when you can search the contents of an electronic document.

What is good documentation? lists some basic metrics for determining whether documentation is useful or not.

Paper and online documentation trade-offs lists the advantages and disadvantages of paper and online documents and relates these to the various types of user.

Why subject matter experts can't write user documents explains why using an outsider is often a sensible approach.

Software usability and documentation shows how a user-centred approach to software design can reduce the requirement for documentation.

Online

Electronic Performance Support Systems compares EPSSs and online help systems.

Context-sensitive help explains context sensitivity and provides a sample application and help file.

Comparison of online help formats lists the basic differences between WinHelp version 4, Microsoft compiled HTML help, WebHelp and pure HTML help. Samples are available.

Web site design and technical communication looks at web design from a technical writing perspective.

Costs

The cost of poor documentation presents a qualitative list of costs to your company.

Reducing the cost of software documentation shows how to reduce costs without compromising on quality.

Relative costs of paper and online documentation compares the costs of development, production and maintenance.

New opportunities for P&P writers, 279 KB. Guest writer Ralph E. Robinson discusses the impact of international standards on the writing of policies and procedures. The article originally appeared in Intercom (www.stc.org/intercom/), November 2005.

Raising the standards contains an overview of ISO/IEC 18019, 'Guidelines for the design and preparation of user documentation for application software' and it outlines how the standard was produced.

Section 508, documentation, and the US software market outlines how you can ensure that your software documentation conforms to the accessibility legislation in the US.

Production

Digital printing for software manuals explains the advantages and disadvantages of digital print technology compared to traditional litho printing.

Bindings for printed manuals explains the trade-offs between the options.

Single sourcing and its applicability to small projects. Single sourcing is used successfully for large documentation projects that involve thousands of pages or help topics. How useful is it for small documentation projects?