Internal, External, Product, Process, Technical, and User Documentation
Have you always needed clarification with many terms referring to different kinds of documentation? Take a look at the following questions.
What do manual and user documentation mean? What's a user manual? Is writing a user manual considered technical documentation? What are the differences between a training manual and an instruction manual? External and internal documentation? Product and process documentation?
Here we'll classify and define all these related terms in a way that makes the most sense, so you'll learn how they're similar or different. However, documentation terms could be used interchangeably; We'll cover them too. So, let's start with defining the most general term in this subject:
Documentation
Documentation is communicable material that formally provides information for introduction, description, training, and instruction regarding a system, product, service, organization, procedure, or technical process. In many cases, these formal and informative documents are also known as Manuals.
Let's go to the next level.
When discussing a product or service, a good classification can divide documentation or manuals into two main groups; Technical Documentation and User Documentation. Another category may divide documents into Product Documentation and Process Documentation, similar to the first category. Another reasonable method to classify documentation, especially concerning organizational settings, is to organize documentation based on being Internal or External.
We'll discuss them all and start with the broadest one.
External Documentation
Preview
As you can guess from its name, external documentation is intended to be shared with people outside an organization (company, business unit, etc.) to provide information and guides regarding a product or service. Therefore, external documentation could also be called Product Documentation. A company's external/product documentation could be divided into User Documentation and System Documentation.
A. User Documentation
User documentation, also known as End-user Documentation, targets end-users to provide comprehensive information about a product or a service. Documents in this group may also be referred to as User Assistance. Their primary purpose is to help the users with helpful information about a product, such as a general introduction, describing its features, and instructions on installing, using, and maintaining it.
Manuals in this group teach subjects by some technical explanation. Still, since the target is end-users, they must limit detailed technical information and use simple language with standard terms and expressions instead of technical jargon. Therefore, they provide user-friendly guides and step-by-step instructions for practical use. Accordingly, although user documentation is in the realm of a technical writer (one who uses the technical information, understands it, and translates it into shorter and simpler content for the end-users), it's not always considered technical documentation. Since they don't usually target experts and professional people. We'll discuss technical documentation later in this article.
Let's review different forms of user documentation:
- Installation and Setup Manual
- Installation and Setup Manual includes detailed information on installing, setting up, and starting a product.
- Instruction Manual
- A manual that instructs the users how to use the product appropriately.
- Troubleshoot Manual
- A manual that addresses how to fix common issues of the product.
- User Manual
- A typical user manual often includes all the guides mentioned above in one place. User manuals focus on different users, including skilled and unskilled, giving instructions on the product's setup, operation, and maintenance. They introduce the product to the users and outline its standard functionality and its different features and applications. They usually include precautions regarding using the product and could also include basic FAQ and troubleshooting.
B. System Documentation
Preview
System documentation might come as a Service Manual or a Repair Manual. System documentation includes an overview of the underlying systems, more detailed technical information, and repair instructions to help mechanics, engineers, and other advanced users repair the product.
Internal Documentation
Internal documentation is not meant to be shared externally. It includes technical details and organizational policy, procedures, etc., which are unnecessary or productive for users. Generally, documents in this group work as a reference for employees, technical teams, managers, or other office workers, to get their job done more efficiently. As mentioned above, Internal documentation can be divided into Technical/Process Documentation and Organization-Support Documentation.
A. Technical Documentation
When we use the term technical documentation, we mean those internal documents distributed mainly among the technical team of an organization. They cover subjects like test plans, development processes, design specifications, project plans, maintenance and improvement of the system, etc., and many technical terms. The term Process Documentation almost refers to the same kind of documents. Technical and process documentation might be used interchangeably.
B. Organization-Support Documentation
In any organization, there are different manuals and documentation for training employees and defining internal organizational guidelines, and most of these documents are in the realm of HR. Let's discuss some of the most common manual-related terms you encounter in an organization:
1. Operation Manual:
This manual includes standards and guidelines of a company that outlines what and how should be done. Therefore, it helps the staff do their job more correctly and efficiently, especially regarding the quality and safety of goods and services.
2. Crisis Management Manual:
It's manual to instruct employees on how to respond to crises in the workplace.
3. Audit Manual:
It describes the auditing policies and procedures of a company.
4. Training Manual:
A training manual is primarily designed to improve performed tasks and could include instruction for training employees. Training Manuals can be used as reference guides for both beginners and familiar/experienced employees.
5. Policy Manual:
A policy manual or a policy and procedure manual is usually a good reference for managers and supervisors to assist them in making decisions and running the business effectively. It contains all company guidelines, rules, and policies, as well as the exact procedures to follow those policies and standards.
6. Organizational Manual:
It defines the organizational structure and includes all the information regarding an organization's positions, tasks, duties, job descriptions, responsibilities, relations, and hierarchies. So, it helps employees know and perform their job position better.
Guides
Now, what is a guide?
Compared to the manual terms we discussed, a guide is a more general term, referring to any manual with guides and help. A guide is not necessarily about using a product. A user guide doesn't have to be comprehensive and could be as simple as a card, giving users some helpful instructions.
Conclusion
Documentation of an organization could be categorized in different methods. One method is to decide which documents will be shared externally and which are not. Detailed technical and company policies and procedures are not intended to be distributed among outsiders. On the other hand, system and user documentation can help users to learn about a company's product as needed. So, let's have a quick review of the main points:
Documentation: The formal descriptive-informative documents | |||
|---|---|---|---|
| Internal Documentation: Targets people within an organization, including technical and office personnel. | External/Product Documentation: targets users and outsiders | ||
| Technical/Process Documentation: Includes project and test plans, designs, and development shared internally with the technical team. | Organization-Support Documentation: Policy, procedures, standards, organizational charts, and training materials of a company. | User Documentation: Targets end-users; the most common form is a user manual. | System Documentation: Targets advanced users (engineers and maintenance personnel) |
User documentation mainly consists of the following:
- Instruction Manual
- Installation Manual
- Troubleshoot Manual
- User Manual
User documentation goal is:
Help users learn about a product and how to:
- Install
- Operate
- Troubleshoot
- Stay users away from possible danger
Technical documentation mainly covers:
- Test plans
- Technical design specification
- Project plans
Technical documentation goal is:
Keep records of the technical process and onboarding technicians of an organization for:
- development
- Testing
- Maintenance
- Improvement