Documentation Product Line

Documentation Product Line

Documentation as product can be produced in three standard formats: hardcopy, PDF (or Microsoft Reader), or online for viewing in HTML or another markup language with Flash components. The following describes each of the standard documentation product offerings:

End User Guides

What is an “end user”?  Webpedia defines it as: “The final or ultimate user of a computer system. The end user is the individual who uses the product after it has been fully developed and marketed. The term is useful because it distinguishes two classes of users, users who require a bug -free and finished product (end users), and users who may use the same product for development purposes. The term end user usually implies an individual with a relatively low level of computer expertise.

Unless you are a programmer or engineer, you are almost certainly an end user.” End user guides are typically less than 100 pages and are targeted toward the end user audience learning about using a piece of software or hardware. The standard end user guide covers common tasks the user can perform using the software or hardware or device. Occasionally, the end user guide includes how to install or implement the software as well as troubleshooting. However, if the software, device, or hardware is complicated or enterprise-related, it is not uncommon to generate a separate installation guide or troubleshooting guide as well as the end user guide.

Because the audience for the end user guide is usually not as technical as a system administrator level, the document is written to a lower reading level, and uses more visual instruction in the form of screen shots of the application, process maps to show sequence of steps, and/or other graphics to identify key components (such as cables for a network architecture).

A common myth from some clients who are not familiar with the large menu of documentation/training offerings available in the industry, is that an end user guide can also serve as a “training guide.” Nothing could be further from the truth. An end user guide focuses on content in a reference or procedural format. In a training guide, information is presented first as a demonstration or instruction, followed by practice sessions using an instructional design approach that meets adult learning theory models. Often, an end user guide is part of a larger documentation solution (i.e., a library of docs including an end user guide, system/administrator guide, etc.).

The end user guide can also be referred to as the “front end” guide. Often, in software technology, the infrastructure for the application splits into a front-end and a back-end; the front-end represents the client interface, and the back-end represents the database, server configurations, and library of code. An end user guide can be produced typically for the external customer; however, end user guides are also required by internal audiences as well. The main difference between the external and internal audience is the packaging. The end user guide for the external customer is considered part of the purchase (i.e., part of the product which is the software, device, or hardware). The end user guide for the internal customer/user is more of a necessary evil. It generates no revenue, however, it is critical within organizations that every user be provided a reference of information to operate various software, machinery, hardware, and so on.

System/Administrator Guides

A system administrator guide, or back-end guide, typically covers configurations, installation, implementation, application, operation, troubleshooting, and any other administrative tasks that the more technical user performs using the application in question. These guides can range anywhere from 50 to 400 pages in length, and usually resemble a phone book in style. The guide can provide procedures, concept overviews, and then generally tends to house large volumes of data reference type information that you would find in high-end technical manuals. This type of manual can certainly be provided to both the external paying customer or for internal audiences as well.

 Policy, Procedure, Process Guides

Internal audiences use policy/procedure, or process guides. Rarely, are these type of guides used for external consumption. A policy and procedure guide is becoming increasingly popular due to Sarbanes-Oxley legislation which dictates that every publicly traded U.S. company provide written procedures for every valid process within their organization. Procedure guides are used for every operation and date back to military days for procedure spec writing. Process guides can be a part of a procedure guide, however, there are stand-alone process guides that illustrate a high-end concept on process, and/or are used in consulting to show a break-down of processes within an organization. These guides are usually anywhere from 50 to 150 pages in length.

Reference Guides

Reference guides can be targeted toward external customers or internal users. They are typically over 100 pages in length and are usually used to provide language references such as API guides (Application Programmer Interface). They are used by a technical user who usually already understands the product (a prerequisite may be to read an end user guide first to learn how to use the product), but requires a reference look-up for various details.

Technical Editing

Every document that is produced for external or internal audiences should be edited. This is performed during a peer review, however, in many organizations a need for a technical edit is required. Part of the technical edit is to identify grammar and clerical problems with the text as well as perform full re-writes of sections where necessary. Style guides are used as the technical editing reference such as the AP Style Guide or the Chicago Manual of Style. A formal edit is performed just as would be done in the publishing house, marking up copy either online or in hardcopy notes, for the writer or source provider.

Online Help

Every application usually provides an online help button or link which gives the user a compressed library of documentation displayed for online viewing (links, drill-downs to other related sections, and a full text search engine). Online help is a deliverable that often must be produced in tandem with the developer because it relies on code that the developer retains in order to run. If the online help is context sensitive (meaning, you can click on words for additional assistance, at the window or page level), the developer must work with the online help author since tags or unique topic IDs must be assigned within the developer’s code in order to make the online help work.

Currently, online help is produced in compiled HTML (.chm) format or Flash. A variety of vendor tools makes this possible, and the help author usually is writing procedures, reference material, and many times, tutorials, all part of the online help package. The difference between the online help deliverable and other documentation products is that the audience is an online viewing audience, and similar to website content, the online help must be presented in a meaningful manner with a discreet amount of links, and architecture which is usually planned out in advance.

Newsletters

Technical information can be presented in a newsletter format for hardcopy or online viewing. Although newsletters are usually associated with marcom or corporate communication deliverables, they are not always used to promote or deliver a message. In many cases, newsletters provide necessary up to date information on a regular basis that a user community relies on in order to make meaningful decisions concerning operations within their organization. There are a wide variety of formats, however usually technical newsletters do not exceed 16 pages in length.