Technical writers enable the successful implementation of products, technologies and services in a variety of industries at many levels. If you were to diversify technical writing you would probably arrive at three main categories:
- Technical writing which shows non-technical readers, that is ordinary folk in the street, how to use something.
- Writing technical manuals for a technical audience, such as engineers and programmers.
- Writing marketing materials and corporate communications for and within technical fields.
A technical writer’s function, most of whom specialise in one or more of the diverse faculties, such as software, medical, engineering and the like, is a lot like a translator or transformer, taking technical information — whether on paper or in the subject matter expert’s brain — and transforming it into terms that are meaningful to the intended audience. As a translator — not from one language to another — but from ‘techno-speak’ into plain old English.
For example, the functional specification of a software program, which would contain many technical terms, is of little help to the end user — who does not really care how or why the program works, but just how to use it properly. The end-user experience is far more successful when the written materials are of a high-quality, expressing the technical and how-to instruction or information in plain simple language and more importantly, the information must be easy to find. Poor or sometimes non-existent user documentation will alienate and frustrate customers.
What must technical writers do to create the effective, easy-to-read style:
Firstly, it is necessary to have the appropriate help authoring tools at hand which boast one of the most important capability factors required of these tools — single-sourcing. Single-sourcing provides the technical writer with the ability to produce output in numerous forms, such as, Compiled help, Web-help, Word and PDF documents including conditional content without having to maintain a separate version for each output type. This capability also allows the writer to re-use many of the source files. This capability allows us to pass on such cost savings to our clients by charging once and supplying three different output products.
Secondly, substance is always the more important requirement of technical writing. However, style is what keeps the reader interested and wanting to read the manual and hopefully learn something from it.
Style constitutes Accuracy, Clarity and Readability. But how do you create a balance with Substance, while it is influenced by the evolving trends in Style:
- Substance includes Accuracy and Clarity.
- Style means ample white space, easy flow layout, with interesting and intelligible language — all of which falls under Readability.
- Accuracy does not mean mind-numbing detail, it means correctness. The written information must describe tasks correctly and accurately.
- Clarity will imply that the writing is simple and easy to read.
- Readability will ensure that the information is actually read .
Collectively then, simplicity becomes the name of the game and readers should not be subjected to flowery, pompous language; the use of a big-word vocabulary must limited as must the redundant wordiness. Straightforward and to-the-point prose is requisite.
Thirdly, the adoption of Web 2.0 technologies to provide user assistance is becoming ubiquitous. Although Web 2.0 has numerous definitions. The term, as described on Wikipedia, basically encapsulates the idea of the proliferation of interconnectivity and social interactions on the Web.
The phrase “Web 2.0″ hints at an improved form of the World Wide Web with technologies such as weblogs (blogs), wikis, podcasts, RSS feeds (and other forms of many-to-many publishing), social software, and web application programming interfaces (APIs) providing enhancements over read-only websites.
However, Web 2.0 technology is not usually applied in the paper-based user manual but references can be made to web-based repositories. CHM or WebHelp local or web-based manuals can use Web 2.0 capabilities.
Finally, Thomas Barker, in his book Writing Software Documentation, uses the term “the default manual” to describe a user’s guide that is organised according to the software’s features, rather than tasks. This sort of user’s guide has a chapter for each menu in a software program, and a section or topic for each command.
The information in a default manual, and in particular the way the information is organised, bears little or no resemblance to what the average user needs to do in their everyday working life.
However important the structure of the default manual is, a well-written manual should include how-to sections which will guide the average user through the day-to-day tasks required when using the software.
