Content Types
Learn about the content types used in user documentation.
Overview
What is it
Required
- A single, high-level topic designed to introduce and explain a product, service, or tool from a technical perspective.
- Focuses on providing essential information, including its purpose, key features, capabilities, and how it fits within the larger system or environment.
- Sets the stage for deeper exploration.
- Avoids detailed step-by-step instructions, focusing instead on the "big picture."
When to use it
- Use to introduce the product, service, or tool to users who are unfamiliar with it.
- Helpful when users need a quick understanding of what the tool or service does without immediately diving into the technical details.
- Orient readers before leading them into more specialized or technical documentation. For example, tutorials, API references, or configuration guides.
EXAMPLES
- Introduction to Scalability
- What is Backstage?
Concepts
What is it
Recommended
- Centers on explaining the underlying principles, theories, or ideas behind a technology or methodology. It's more about the 'WHY' and conceptual understanding.
- Usually provides a high-level overview, explaining concepts and ideas without delving into technical specifics.
- Generally presented in a narrative format, discussing concepts in a logical, often sequential manner.
- More likely to be read once or occasionally to build foundational understanding.
When to use it
- When introducing a new technology or concept that requires foundational understanding before practical application.
- Before users dive into procedural guides or tutorials, to give them the necessary context.
- When explaining complex ideas that benefit from a higher-level overview before getting into specific technical details.
- When there's a need to clarify the reasoning behind design decisions, trade-offs, or technical choices.
EXAMPLES
- Understanding Microservices Architecture
- What is Containerization and When is it Beneficial?
Getting started
What is it
Recommended
- Concentrates on the basics of the product or service, how to set it up, and how to perform key tasks.
- Tends to be shorter, aiming for quick assimilation of basic information.
When to use it
- Used at the beginning of a user's journey.
- Aimed at product or service users, focusing on the functional aspects of how to use it.
EXAMPLES
- Getting started with Zoom
- Getting Started with React
What's the difference between a Getting Started and How-to topic?
Both serve distinct but complementary purposes. While both aim to assist users in understanding and using a product, service, or tool, they differ in scope, detail, and intended user.
Similarities
- Both are designed to provide step-by-step assistance, helping users accomplish specific tasks or understand product functionalities. They are usually sequential, guiding users through a logical order.
- Both focus on the user's perspective, presenting information clearly and easily digestibly.
- Both often incorporate visuals like screenshots, diagrams, or videos to enhance understanding.
Differences
| Getting Started | How-to |
|---|---|
Focused on the basics of a specific product or tool. It's usually concise, covering only what is necessary to effectively use the product or tool. It is often used for single sessions and is designed for quick reference and immediate application. | Provides in-depth instructions on a specific scenario or goal. It's focused on detailed processes. Designed for users who have basic knowledge but need guidance on specific functions. Goes into detailed steps, often covering complex tasks or advanced features. Can be lengthier and more complex, depending on the scenario's complexity. |
How-to
What is it
Required
- Aimed at guiding users through a scenario-based process or task from start to finish (end-to-end process). It focuses on the 'How.'
- Typically follows a linear, sequential format. It often provides the bare minimum level of relevant information needed to complete a task. Tutorials dive deeper into the subject.
When to use it
- Provide guidelines for completing a specific scenario or goal.
- Addressing frequently asked questions or complex scenarios.
EXAMPLES
- Setting up a Zoom webinar
- Integrating API X into your app
What's the difference between a How-to and Getting Started topic?
Both serve distinct but complementary purposes. While both aim to assist users in understanding and using a product, service, or tool, they differ in scope, detail, and intended user.
Similarities
- Both are designed to provide step-by-step assistance, helping users accomplish specific tasks or understand product functionalities. They are usually sequential, guiding users through a logical order.
- Both focus on the user's perspective, presenting information clearly and easily digestibly.
- Both often incorporate visuals like screenshots, diagrams, or videos to enhance understanding.
Differences
| How-to | Getting Started |
|---|---|
Provides in-depth instructions on a specific scenario or goal. It's focused on detailed processes. Designed for users who have basic knowledge but need guidance on specific functions. Goes into detailed steps, often covering complex tasks or advanced features. Can be lengthier and more complex, depending on the scenario's complexity. | Focused on the basics of a specific product or tool. It's usually concise, covering only what is necessary to effectively use the product or tool. It is often used for single sessions and is designed for quick reference and immediate application. |
What's the difference between a How-to and a Tutorial topic?
Both How-to and Tutorial topics are essential components of technical documentation that guide users through specific processes or tasks. While they share some similarities, they also have distinct characteristics that set them apart.
Similarities
- Both provide structured, sequential instructions to help users achieve a specific outcome.
- They focus on completing a particular task or process, though Tutorials tend to offer more context.
- Both offer clear instructions on accomplishing something, with Tutorials typically providing more in-depth explanations.
- These formats are designed to meet the needs of users seeking guidance on tasks or skills, with Tutorials often offering a more comprehensive learning experience.
Differences
| How-to | Tutorial |
|---|---|
|
|
Troubleshooting
What is it
Recommended
- Focuses on diagnosing and resolving specific issues or errors encountered by users.
- Addresses multiple potential causes and solutions, often taking a non-linear approach to account for various variables that might lead to the issue.
- Guides the user through logical steps to identify the root cause and resolve the problem.
- Generally reactive and designed to handle user frustration or confusion when something isn't working as expected.
When to use it
- Users encounter unexpected issues or specific error messages while using your product or service.
- Users don't know where to start solving a problem and need straightforward, step-by-step guidance.
- Providing multiple paths to resolution, as problems often have more than one potential cause.
- Minimizing user frustration by addressing frequent or common errors quickly and effectively.
EXAMPLES
- Resolving Version Mismatch Errors in Microservices
- Fixing Error Code 404 in API Requests
References
What is it
Recommended
- Provides detailed, structured information about specific elements, such as APIs, PowerShell cmdlets, CLI commands, configuration settings, or database schema.
- Focuses on factual and descriptive content, often presented in a tabular or list format, including inputs, outputs, parameters, syntax, and usage examples.
- Serve as a precise guide for developers, engineers, or users who need specific information without extensive conceptual explanations.
When to use it
- Users need quick, accurate, and specific details about a command, function, or feature they are implementing or troubleshooting.
- User already understands the high-level concepts and is looking for the correct syntax, arguments, or options.
- Documenting APIs, software commands, configuration options, or any technical component with clear parameters and usage contexts.
- Users need quick access to factual data rather than explaining why or how something works.
EXAMPLES
- API Reference: Authentication Endpoints
- Database Schema Reference: User Table
Tutorials
What is it
Optional
- Educational and explanatory content that guides users through a specific process or task, step by step.
- Offers clear instructions on how to accomplish something, explaining the reasoning behind each action, the concepts involved, and how the steps fit into the broader context.
- Aims to teach users new skills, workflows, or methods, fostering a deeper understanding of the subject matter.
When to use it
- Guide users through performing specific tasks, especially those new or unfamiliar to the audience.
- Facilitate learning through hands-on activities and problem-solving exercises.
- Support onboarding, introduce new features, or explain complex procedures that require a thorough understanding of the steps and their underlying rationale.
EXAMPLES
- Building Your First React Component
- Writing Your First Unit Test Using Jest
What's the difference between a Tutorial and a How-to topic?
Both How-to and Tutorial topics are essential components of technical documentation that guide users through specific processes or tasks. While they share some similarities, they also have distinct characteristics that set them apart.
Similarities
- Both provide structured, sequential instructions to help users achieve a specific outcome.
- They focus on completing a particular task or process, though Tutorials tend to offer more context.
- Both offer clear instructions on accomplishing something, with Tutorials typically providing more in-depth explanations.
- These formats are designed to meet the needs of users seeking guidance on tasks or skills, with Tutorials often offering a more comprehensive learning experience.
Differences
| Tutorial | How-to |
|---|---|
|
|