Documentation is material that is used to describe, explain or instruct readers about attributes of an object, system or procedure. As a form of knowledge management / organization, documentation can be provided on paper, online, or on digital or analog media. See also Documentation Platforms & Tools.
My personal leitmotif for writing documentation:
“Use as few words as possible, but as many as necessary.”
Types of Documentation
Technical Documentation:
- Purpose: Detailed documentation aimed at developers, engineers, or technically savvy users, explaining how to build, maintain, or modify products.
- Audience: Developers, IT professionals, system administrators.
- Examples: API documentation, system architecture docs, code documentation.
Internal Documentation:
- Purpose: Maintains institutional knowledge within an organization, including best practices, project details, and internal procedures.
- Audience: Employees, internal teams.
- Examples: Wiki pages, internal guides, project documentation.
Policy Documentation:
- Purpose: Outlines organizational policies, compliance guidelines, and rules.
- Audience: Employees, stakeholders, regulatory bodies.
- Examples: Privacy policies, HR policies, security policies.
Process Documentation:
- Purpose: Outlines the steps, policies, and procedures involved in business or operational processes.
- Audience: Internal staff, managers, or compliance officers.
- Examples: SOPs (Standard Operating Procedures), process maps.
Legal Documentation:
- Purpose: Contains legal agreements, terms of service, and contracts.
- Audience: Customers, partners, legal teams.
- Examples: Terms of service, EULAs (End-User License Agreements), contracts.
Pharmaceutical Documentation:
- Purpose: Ensures that medications are used safely and effectively, meet regulatory standards, and provide critical information to both patients and healthcare professionals.
- Audience: Depending on the type, the audience can include patients, caregivers, healthcare professionals, regulatory bodies, and pharmaceutical companies.
- Examples: Ranging from patient leaflets and medication guides to clinical study reports and regulatory submissions, these documents are integral to the lifecycle of a medication.
Resources
Personal Resources
Writing conventions:
Templates for Topics:
- Tutorials
- Task Topics
- Release Notes
- Reference Articles
- Overview Pages
- How-to Articles
- Concept Topics
Help Center
- Purpose: Empowers users to find answers and resolve issues independently (self-service), improving customer satisfaction and reducing the load on customer support teams.
- Audience: Eend-users, customers, and occasionally internal staff, depending on whether the Help Center is public-facing or internal.
- Examples: A SaaS provider might have a Help Center with articles on how to use different features, troubleshoot common issues, and access training materials.
Note
Key features of a Help Center:
- Knowledge Base
- Search functionality
- Contact options
- Interactive elements like a chatbot or interactive tutorials
- Community Forums
- Product updates & announcements
- User feedback mechanisms
Knowledge Base (KB)
- Purpose: A repository of articles and FAQs to help users solve problems, answer questions, or understand products/services.
- Audience: End-users, customers, or internal staff.
- Examples: FAQ pages, troubleshooting guides, how-to articles.
Online Help
- Purpose: Provides context-sensitive assistance, often embedded within software, to guide users through specific tasks or issues.
- Audience: End-users of software applications.
- Examples: Tooltips, help buttons that link to specific articles, interactive tutorials.
User Manuals (User Guides)
- Purpose: Comprehensive instructions on how to use a product or service, covering everything from setup to advanced features.
- Audience: End-users.
- Examples: Printed or digital manuals included with products.
API Documentation
- Purpose: Describes how to effectively use and integrate with an API, including endpoints, request/response formats, and code examples.
- Audience: Developers.
- Examples: REST API documentation, SDK documentation.
Release Notes
- Purpose: Summarizes changes, improvements, and fixes in a new version of software or a product.
- Audience: Users, administrators, and developers.
- Examples: Version history, changelogs.
Training Materials
- Purpose: Provides educational content to help users or employees learn how to use a product or perform tasks.
- Audience: End-users, employees, trainers.
- Examples: eLearning modules, instructional videos, training manuals.
White Papers
- Purpose: Authoritative reports or guides that inform readers about complex issues, often used in B2B marketing or to explain technologies.
- Audience: Decision-makers, industry professionals, technical audiences.
- Examples: Research papers, technical overviews, industry analysis.
Case Studies
- Purpose: Describes how a product or service has been successfully used by a customer, showcasing benefits and solutions.
- Audience: Potential customers, sales teams.
- Examples: Customer success stories, project reports.
Product Specifications (Specs)
- Purpose: Detailed descriptions of a product’s features, capabilities, and technical requirements.
- Audience: Engineers, developers, procurement teams.
- Examples: Product data sheets, technical specs documents.