Choosing the correct types of technical publication that will compliment your products and provide the necessary support information is essential. We have extensive experience of writing all forms of technical publication and are happy to help you make the best choices to meet your specific requirements.
There are many different types of technical publication, including online help, user guides, reference manuals, installation instructions, quick-start instructions, training manuals, engineering guides and data sheets, and each has a specific purpose. The following sections outline the typical purpose and content of some of the common types of technical publication.
 Most software applications should be provided with online help. If you have a large application with many options and features, it is often preferable to explain the detail of how an option or feature works within online help, since it is particularly good at providing reference information that is easy to access.
The example shown here is an online help system for a Computer-Aided Engineering (CAE) application used for the design of integrated circuits. The help was developed using Adobe RoboHelp and provided in webhelp format, which uses a separate HTML file for each topic. Webhelp is displayed in a browser and is often the choice for both web-based applications and those that can run under different operating systems. A benefit of webhelp for web-based applications is that it helps to minimise the amount of data downloaded when the user views the help system.
An alternative format for Microsoft Windows applications is CHM (Compiled HTML), which allows an entire help system to be contained in a single file.
To maximise the benefits of online help, it is recommended that the software developer adds a Help button to each screen within the application. This enables the online help to be context sensitive, which means that when a user clicks a Help button, the topic that is relevant to the current screen is displayed automatically. With context-sensitive help, there is no need for the user to search through the help system to find the appropriate information.
Localising online help
One consideration when providing online help is localisation. If the software is to be available in different countries, the online help may need to be translated.
Many translation agencies find translating online help problematic, since they rarely have access to help-development tools such as RoboHelp and are unlikely to have significant knowledge of HTML. We have overcome this problem by developing our own bespoke software tools that allow a translator to translate an online help system using nothing more than Microsoft Word or other word processor.
The translators require no exposure to HTML and need no specialist software. Once the translation is complete, our tools insert the foreign text into the RoboHelp source files, while intelligently maintaining the hyperlinks and text formatting. We have found that this process simplifies translation and reduces risk, and we are aware of no other company that can offer this service.
 A user guide introduces a system for new users. Typically, a user guide starts with a description of the concepts and key features of the system. Later chapters provide an overview of how to use the product.
Generally, a user guide should not describe every option and feature in detail, since to do so may reduce the document's appeal as a guide. The detailed information is often better placed in other publications such as online help, reference manuals or installation instructions. The aim of a user guide is mainly to provide introductory information, and therefore is of particular use to new users.
It is normal to provide a user guide as a PDF document, which allows it to be easily viewed and printed.
The example shown above is a page from a user guide of a security system, developed using Microsoft Word. The client prefers publications to be developed using Microsoft Word to facilitate translation and to make it easy for other personnel within the company to use the source documents. We have written a large number of different technical publications for this client, which is one of the largest manufacturers of security equipment in the world.
Today, e-learning is often used in preference to user guides for software applications, particularly for those that have a highly-graphical user interface. Our About E-Learning page provides further information about this rapidly-growing media type.
 Most people are aware of the purpose of a quick-start or getting-started guide - to cover the basics and to get the user up and running as quickly as possible. The guide may include basic installation instructions and information on how to get the product running for the first time.
When developing a quick-start or getting-started guide it is essential to focus on the usability and size of the publication. The user is generally impatient to get started, and will want to read only a few well-written pages that have minimal detail. Very simple instructions, with as few words as possible and helpful illustrations are key design concepts.
Generally, a quick-start guide is of little use once it has been read for the first time, which is a shame considering the amount of effort that goes into its development! Other publications such as user guides, e-learning and online help are used to progress the user's knowledge beyond the getting-started stage.
The picture shown opposite is an example of a quick-start guide for product that uses satellite technology to track personnel or vehicles.
The client is registered on the Fortune 100, which lists the top 100 companies in the United States.
Installation instructions explain how to install hardware or software products and are often made available as hardcopy documents within the product packaging or with the media.
Depending on the type of product, hardware and software installation instructions may be provided in the same document, or separate instructions may be more appropriate, particularly if different people are responsible for installing the different components. In addition, installation instructions may be combined with "quick-start" information if it is of benefit to the reader.
Installation instructions for hardware generally benefit from good use of annotated illustrations. In some cases, language-independent instructions may be a requirement to avoid the need to translate the document into multiple languages.
 An engineering guide introduces the system for the benefit of engineers, installers or support personnel. Normally, the guide starts with a description of the concepts and architecture of the system, with later chapters providing an overview of how to install and configure the hardware and/or software components.
An engineering guide is similar in concept to a user guide: it should not describe every engineering option or installation feature in detail, since to do so will reduce the document's appeal as a guide. The aim of an engineering guide is mainly to introduce the product for the
benefit of new engineers or installers.
An engineering guide is often provided as a PDF file, which allows it to be easily viewed and printed.
The example shown above is a page from an engineering guide developed using Adobe FrameMaker for a large international manufacturer of heating and ventilation control systems. We have developed a large number of engineering guides, online help, data sheets, user guides and installation instructions for this client, across many different products and releases.
 Data sheets provide pre-sales information for hardware or software products. They are usually small documents of only one or two double-sided pages.
The required layout of a data sheet is normally fairly standard: the front page often contains a picture or graphic of the product, a short description and the key features. The remaining pages generally provide detailed specifications. For some publications, the inclusion of typical use cases may be appropriate.
The primary aim of a data sheet is to sell a product, and this requires a very different style of English from that used in other technical publication types. The language must be up-beat, confident and flow easily.
Note: The examples on this page have been modified to protect the identity of our clients.
| 
