The Different Types of Manuals in Technical Writing

This guest blog post instruction manual to technical writing was written by Daniel Lemke, a Principal Implementation Consultant for Thomson Reuters. Daniel has worked with MadCap Flare since version 9, administering and supporting its use for the documentation teams he has worked in. Daniel will be discussing various technical manual examples. 

I've been a full-time technical writer on documentation teams at three different companies over a span of just over eight years. One characteristic I repeatedly witness and, naively for sure, am repeatedly amazed by, is the diversity of names for the types of manuals in technical writing. From organization to organization, business unit to business unit, and sometimes even writer to writer, the same kinds of manuals have different titles.

When it comes to updating and writing technical documentation, it helps me to group an organization's library of manuals into high-level categories (and then standardize them; more on that later). At the highest level, I like to group manuals into the following categories, somewhat grouped by the intended audience (although the audience types are not always different people). For organizations lacking the internal resources, engaging technical writing services can streamline this standardization process.

There are three basic examples of technical documentation:

• User documentation
• Administration documentation
• Developer documentation

User Documentation

User documentation applies to anything that helps your readers interact with your product or service. This is where I see the most variation in names (and in how the content is organized). Product Documentation, User Guides, One Sheets, Job Aids, Quick Cards, Feature Documents, Quick Starts, Help, How-to, Walkthroughs, Tutorials (just to name a few). The common thread, regardless of the names or how the content is split apart, is that the reader learns what the product does and how to make it do so.

User documentation is typically some combination of explanations, steps or workflows, and reference information. The following are the types of user documentation I've seen and the kinds of information they contain.

• User Guide: often a comprehensive user manual for a product or service, including conceptual information, step-by-step clear instructions, and reference information throughout. At a minimum, a user guide should describe what the user will see and explain what the user can do in a product.
• Quick Start: a short technical document with just enough information to help someone become productive with your product.
• Job Aid: a procedure for a specific task or a larger workflow for a specific job function, usually with no extra detail beyond the steps. A common analogy for these is a recipe, although this breaks down some in the age of food bloggers who describe their first European vacation before telling you at what temperature to preheat your oven.
• Guided Assistance: an overlay, pop-ups, or similar that walk the user through specific tasks, especially for new users or new features.

Take care, especially in certain domains, to avoid the prescribing policy. Clearly distinguish between examples and requirements to avoid taking on undue liability.

Audience

• End-users
• Internal, customer-facing staff
• Competitors

Potential Subject Matter Experts on Technical Documentation

• Product Managers and Product Owners
• Quality Assurance
• Implementation and Support

Administrator Documentation

Administrator documentation helps IT resources get the software running initially and continue operating according to the evolving needs of an organization through the use of an instructional document. Often these technical content guides combine some or all of the following subjects:

• Technical Specifications and Architecture Diagrams: this may include technical information about the product design, technology used, security, network layout, etc.
• System Requirements and Prerequisites: describes any hardware or software development requirements and prerequisites for installing, configuring, and using a product.
• Installations and Upgrades: User instructions that guide the reader through all the steps necessary to install or upgrade a product.
• Scheduling and Automation: explain tasks related to scheduling jobs such as recurring reports or processing data.
• Resource Estimation and Sizing: especially for on-premises software, this can help system administrators estimate hardware and software needs for a product to handle the throughput.
• Troubleshooting: common issues, troubleshooting steps, and subsequent support procedures specific to a product.
• Maintenance: provides suggestions for ongoing maintenance of a product, for example, cleaning up temporary storage or log files.

The audience for these manuals may very likely be folks who are not and will not become familiar with the product and its day-to-day use. They just need to get it set up and keep it running for the end-users. They will likely appreciate your brevity.

I've often seen most or all of the setup topics combined into a single installation or upgrade guide, beginning with prerequisites, followed by all the procedures required to complete installation and configuration, and concluded with some troubleshooting tips.

Audience

• IT Staff
• 3rd Party Vendors and Contractors

Potential Subject Matter Experts

• Developers
• Quality Assurance
• System Admins
• Implementation and Support

Developer Documentation

Developer documentation includes anything that helps a developer interact with your product or content through technical communication.

Most of the time, the audience for these kinds of manuals appreciate you getting them up and running with a sample application as quickly as possible. Their standard operating procedure is likely to be something like so:

1. Compile from a sample
2. Run it and see what happens
3. Make some changes
4. Recompile and see what happens this time
5. And so on.

Your software developer documentation will mostly be for reference and troubleshooting. Types of developer documentation may include:

• API Docs: a suite of documentation covering authorization and authentication, available endpoints, field definitions, and payload samples. In many cases, some or all API documentation is automatically generated based on information contained in the APIs.
• SDK Cookbooks: along the same lines as API documentation, these should give a developer all the information they need to get a custom application up and running using an SDK provided for your product.
• Data Dictionaries: contains data definitions and table structure for a product.
• Code Samples: sample scripts or sample applications designed to give the developer a quick turnaround in creating something that can interact with your product.

Audience

• Developers
• Stakeholders

Potential Subject Matter Experts

• Product Managers and Product Owners
• Developers
• Quality Assurance

Release Notes

Release notes explain, briefly, what changed in a release. This should include new features, bug fixes, updates to prerequisites or system requirements, and sometimes special notices relevant to the customer.

Release notes should tell your readers the following:

• What differences to expect
• If you fixed bugs they reported
• If you implemented features they requested
• If the effort to upgrade is worth the benefits

I have seen and, begrudgingly, deployed release notes that read more like a user manual (complete with screenshots) and included information only relevant to internal teams. Avoid these pitfalls when possible because they are likely to scare away your intended audience. My favorite release notes are simple, text-only bulleted lists. If you think more information is needed for an item, consider a hyperlink to a relevant topic or, in some cases, a supplemental technical document.

Honorable Mentions

The following are kinds of technical documentation that may not fit into the previous categories or are a bit too much of a stretch to include under the banner or manuals but that you may still work on as a technical writer.

• Microcopy: small bits of content used in the product such as field names or tool tips.
• White papers: typically more marketing-focused documents discussing a feature or problem and solution at a high level.
• Bug Notes: a list of outstanding bugs that may affect or we reported by customers.

Standardizing Manual Names

I actually enjoy this problem because I like helping, and I think tackling this issue is a great way to simultaneously simplify internal processes and improve the user experience. I approach it like so:

1. Evaluate the types of manuals an organization is producing
2. Assign each type to high-level categories
3. Devise a standard set of names
4. Document the new standards
5. Implement the new standards

Below are some notes and tips for working through this task.

• Get support from someone in a leadership role. You may be surprised by whose feathers are ruffled by your benevolent meddling.
• From every technical documentation contributor on your team or in your organization, request they send you the name and an example of each type of document they create.
• When devising the new standards, consider the impact to customers for any drastic changes. Sometimes it's a better customer experience to avoid pedantry.
• Document the new standards. Yes, this is just the same thing I wrote in step 4. It's important, and if you're a technical writer, you probably want to do this already anyway.

Feedback!

Did I leave out your favorite type of manual? Do you have a success story or tips about standardizing naming conventions at your organization? Let us all know in the comments!