The Owner's Manual as Engineering Spec

by Christopher Moore, Seven Woods Audio, Inc.

Writing the Owner's Manual before beginning design will help you get a better product in less time.

Most companies require a comprehensive specification before development begins. While there are many benefits to this, creating the specification is sometimes a formidable task in its own right. The author of the specification often finds himself not just specifying performance, but describing the product's behavior in response to user actions and in various circumstances. If the product has much software content, the specification may even begin to describe display states, user interface controls, and menu structures. Beyond a certain point, the specification begins to resemble an owner's manual. Why not just create the owner's manual first and shape it into a form that will also serve as a product specification? I used the technique during the development of a complex product involving hardware and several layers of software, and it worked very well.

Benefits and uses:

This approach has several benefits:

It facilitates getting end user input not only at the beginning of a project but during it as well. End users get a real feeling for the product from a well done owner's manual and can react to it before design has gone too far.
The owner's manual is a better format than a traditional product specification for many products.
Management will find the format familiar, making it easier to obtain their buy-in.
Marketing and sales are more likely to read an owner's manual than a specification, increasing the chance that their perspective can be considered early.
The design team will refer to the owner's manual throughout the development process and will have a clearer image of the product and its uses.
When the product is complete, the final owner's manual is more likely to be available on time.

Contents of the owner's manual

The contents and format of the owner's manual will vary considerably from product to product and should be shaped by the needs of the team and company specification requirements. While the manual will probably contain all the material eventually intended for end users, it will also contain material that will be deleted later.

The following outline is a good starting point for the manual:

Executive summary
Table of contents
Introduction
Features
Installation
Functions, modes, and operations
Menu tree, menu items, screen designs, etc.
Controls and displays
Inputs and outputs
Options available at first release
Options planned for sequenced release during the product lifetime
Specifications
Worldwide markets to be served
Regulatory compliances
Warranty
Glossary of terms
Revision history of the owner's manual
List of other relevant documents
Product limitations and boundaries
Open issues

Techniques for creating and maintaining the manual

Since the manual will probably be given to a variety of readers, including some end users, the authoring tools must support the creation of a manual that can be distributed with at least two levels of information. The copies given to end users should have confidential information removed. The software used for writing and/or desk top publishing must support this via features such as hidden text, footnotes, end notes, or buried labels. I used suppressible footnotes to hide private material from the end user's version. Microsoft Word's hidden text feature should also work well. While one could sometimes identify a need for more than two versions of the manual, that would probably prove too cumbersome.

Appendices can be used to hide entire blocks of private material, such as future options, a list of other relevant documents, the statement of product limitations, and open issues. Place these appendices at the end of the manual and suppress them from the table of contents and the manual.

For a specification to be valuable, it must be kept up to date and be readily available in its current form. Each time you open up the manual after any copies have been distributed, execute the pending revisions before you begin the new round of revisions. Then turn on the revision marking feature of your word processor and make the updates. Your readers will appreciate the time savings as they scan the manual for changes made since the last version. You may find it useful to place a date stamp at the beginning of all material added during this session. Use a footer on each page that bears the current revision date.

If your team is working at networked computers or workstations, you should strongly consider placing the manual on line. Typically, one person "owns" the manual and has write/modify privilege, while others have read-only privilege. However, if your software permits it, you may enable certain readers to make additions and comments using the revision feature. Microsoft Word allows multiple authors to embed their revisions, capturing initials and dates for each revision. It is then up to the "owner" to review and keep or discard these comments. My instinct, however, is that this is probably more fraught with the risk of errors and hassles than it is worth. Whether the document is shared over a network or via paper copies, the readers can communicate comments and correct errors without opening up the master copy.Graphics, pictures, screen dumps, and diagrams are essential in any good manual and should be supported to the greatest extent consistent with good working efficiency. If the writer is not artistic enough or doesn't have command of the computer tools required, he should be supported by someone who does.

Who should write the manual

Finding the right author is essential to making this idea work. Likely candidates include the product champion, a team member who writes well, a lead end user, a company technical writer, or a consultant. The author needs to be a good communicator, proficient with the software tools, and someone who will be available for the duration of the project. Ideally, he will be able to grasp and comprehend all of the facets of the product, to hold it all in his head. At the same time, the writer's ego should not prevent him from enlisting the talents of other contributors, such as technical specialists and graphic artists.

When this technique makes sense and when it doesn't

An owner's manual as specification is especially useful if the product has much software content, has a rich user interface, or requires complex installation or operational instructions. It is less useful if the product is simple and has very little end user interaction.

The technique will prove especially beneficial to companies that value customer input during product definition and design.

Products that lend themselves to modular design (where design chunks can be partitioned and distributed among the team) will especially benefit from a manual that gives each team member a picture of the total product.

If you haven't got a good author, it will be impractical to create an owner's manual in this form.

Variations on the idea

If creating the entire manual seems like too much effort, consider writing selected sections, as needed. These can be used to walk through how a feature or subsystem of the product will function. If you can't explain to an imaginary end user how something will work, you probably don't adequately understand the problem or your own solution. You can also create individual documents for the glossary, open issues, the menu tree, and product limitations.

There is probably an interesting convergence among the following "documents:"

specification
owner's manual in printed form
on-line help system for a computer based product.

Perhaps in some situations the owner's manual should be created as an on-line help system as its primary format.

Acknowledgements

Thanks go to Barry Blesser for first suggesting this technique to me. More information, and a lengthy list of references, can be found in:

R. McIntosh Shand, "User manuals as project management tools: Part 1--Theoretical background." IEEE Trans. Prof. Commun., vol.37, no.2, pp. 75-80, 1994.
R. McIntosh Shand, "User manuals as project management tools: Part 2--Practical Applications." IEEE Trans. Prof. Commun., vol. 37, no. 3, pp. 123-142, 1994.

Christopher Moore, principal of Seven Woods Audio, is an electrical engineering consultant specializing in the conception and design of products and circuits used in audio applications.
Seven Woods Audio is committed to helping manufacturers quickly create digital or analog audio products that generate a good return on investment, work right the first time, sound excellent, and please the end user. The company works with manufacturers of professional audio, consumer audio, broadcast, telecommunications, and computer equipment.

E-mail the author at 72674.1022@compuserve.com

Top of this article | s2n home | Article Index