Latest posts by techwriter (see all)
- Test Your Knowledge of 4 Basic Fonts – Drag & Drop - January 27, 2017
- How NOT to Design a Web Site - January 25, 2017
- Hazards of Poorly Written Technical Documentation - December 26, 2016
© 2010 Ugur Akinci
Some of my readers asked the differences between three types of technical documents used frequently in the software-hardware sector: User Guide, Startup Guide, and Quick Reference Guide. Sometimes the demarcation line gets blurred, especially if you’re new in the business.
A USER GUIDE is the easiest to define: it’s the “bible” of the product in question. It includes anything and everything (including the proverbial and metaphorical “kitchen sink”) that a user needs to know about the software/hardware in question. It is detailed, comprehensive, and exhaustive.
A tell-tale sign of a good user guide is that, every time the author describes how to ADD (or CREATE) a component, he/she also immediately describes how to EDIT (or MODIFY) and DELETE the same component, for completeness.
A USER GUIDE is written to answer any question or contingency WITHOUT, however, describing any specific configuration or operational procedure to follow.
A STARTUP GUIDE (or a “Quick Startup Guide” as it’s sometimes also called), on the other hand, is all about the step-by-step PROCEDURE to follow to setup the system/product and to make it “work,” to “get it going.” Once the system is up and running, then the user can consult all that detailed information in the User Guide and change the settings and the way the system performs to his/her heart’s content.
But the Startup Guide describes only one or at most two different ways to set up a system, not all the different possibilities. It also describes how to add/create components or modules and not necessarily how to edit or delete them. For that you need to consult the User Guide.
This is the reason why User Guides are usually long documents since they are all inclusive. Once I wrote a 1,000 page user guide with a wonderful colleague of mine. I still remember that one because we both spent a few sleepless nights to finish it under a tight deadline pressure. (I’m happy to say the project was a success and that same user guide is still shipped to the customers today even though it went through quite a few revisions.)
A QUICK REFERENCE GUIDE neither describes the procedures required to set up a basic system configuration nor it’s comprehensive in the way a User Guide is. You can say that a Quick Reference Guide is a user guide stripped off all it’s textual fabric and boiled down to basic system specs (specifications).
For example, if you’d like to read how to connect wires to a terminal block in a step-by-step manner, then you need to read the USer Guide. But if you want to learn right away which wire is connected to which terminal, then there should be a table in the Quick Reference Guide listing the connections without any lengthy explanations.
Another example: if you need to learn how to power-up the system quickly and get the “lights flashing” (so to speak) then you need to read the Quick Startup Guide. But if you are curious about the voltage range within which the system operates, then the Quick Reference Guide is where that information should definitely be.