### Tutorial Example: Getting Started with Authentication

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/common-distinctions.md

Illustrates the structure and goal of a tutorial focused on learning authentication concepts and implementing a basic login system for a novice user.

```text
Title: "Getting started with authentication"

Goal: Help a new user understand authentication and 
implement a basic login system

Flow:
1. Explain what authentication is
2. Create a simple login form
3. Add password checking
4. See the system work end-to-end
5. Understand the concepts you've encountered
```

--------------------------------

### How-to Guide Example: Set Up Two-Factor Authentication

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/common-distinctions.md

Demonstrates the structure and goal of a how-to guide for an experienced user to implement a specific feature, two-factor authentication.

```text
Title: "How to set up two-factor authentication"

Goal: Help an already-competent user implement 2FA 
for their application

Flow:
1. Install the authentication library (assumes they know what they're doing)
2. Add 2FA provider configuration
3. Enable 2FA for users
4. Test the implementation
```

--------------------------------

### How-to Guide: Database Connection Pooling

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/common-distinctions.md

This example demonstrates the structure of a how-to guide, focusing on solving a specific user problem related to database connection pooling performance.

```markdown
Title: "How to configure database connection pooling for performance"

Problem: You're experiencing connection timeouts under load.

Solution:
1. Identify current pool size...
2. Calculate appropriate pool size...
3. Configure pool parameters...
4. Monitor improvements...
```

--------------------------------

### Step Structure Example

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/how-to-guides.md

Demonstrates the recommended pattern for structuring individual steps within a how-to guide, linking action to purpose.

```markdown
[Action] [to achieve/so that] [purpose/outcome]

Example:
"Navigate to the Admin panel so that you can access user management settings."

```

--------------------------------

### Example How-to Landing Page Structure

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/complex-hierarchies.md

Illustrates a typical structure for a 'How-to' landing page, including section headings and lists of links to specific guides. This format helps break down complex topics into manageable sections for the user.

```text
How to guides
=============

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Installation guides
-------------------
Pellentesque malesuada, ipsum ac mollis pellentesque, risus
nunc ornare odio, et imperdiet dui mi et dui. Phasellus vel
porta turpis. In feugiat ultricies ipsum.

* Local installation       |
* Docker                   |
* Virtual machines         |
* Linux containers         |

Deployment and scaling
-----------------------

Morbi sed scelerisque ligula. In dictum lacus quis felis
facilisisvulputate. Quisque lacinia condimentum ipsum
laoreet tempus.

* Deploy an instance       |
* Scale your application   |

```

--------------------------------

### Referencing Configuration Reference from How-to Guides

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/reference.md

This snippet shows how a how-to guide can direct users to the configuration reference for a complete list of options.

```text
"For all available options, see the configuration reference."
```

--------------------------------

### Referencing API Reference from How-to Guides

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/reference.md

This snippet demonstrates how a how-to guide can link to the API reference for parameter details.

```text
"Complete list of parameters available at [Reference]."
```

--------------------------------

### Effective How-to Guide Titles

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/how-to-guides.md

Demonstrates the use of clear and specific titles for how-to guides. Titles should clearly state the goal and use a 'How to' format to set reader expectations and improve searchability.

```text
GOOD:   "How to integrate application performance monitoring"
BAD:    "Integrating application performance monitoring" 
        (unclear if this is how-to or explanatory)
VERY BAD: "Application performance monitoring"
          (completely ambiguous)
```

--------------------------------

### Conditional Steps Example

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/how-to-guides.md

Illustrates how to present conditional steps using 'if' statements or decision trees for alternative scenarios.

```markdown
If you're using [condition], do X.
If you're using [condition], do Y.

Or use decision trees:

Do you need to [handle case A]? 
  - Yes: See "Handling case A"
  - No: Continue with step 3

```

--------------------------------

### Tutorial Example: Database Transactions

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/common-distinctions.md

This snippet shows how a tutorial on database transactions would be structured, focusing on hands-on steps and observable results for the learner.

```markdown
Title: "Getting started with database transactions"

Let's create your first transactional application.

Step 1: Create a simple transaction
- Write this code...
- Run it and observe...

Step 2: Add error handling
- Modify the code...
- Test it with this scenario...

Step 3: Verify transaction behavior
- Watch what happens when...
- Notice how...
```

--------------------------------

### Referencing API Reference for Customization in Tutorials

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/reference.md

This snippet shows how a tutorial can guide users to the reference documentation for further customization options.

```text
"If you want to customize this further, see [Reference]."
```

--------------------------------

### Common Mistake 2: How-to Guide Loaded with Learning Content

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/common-distinctions.md

Highlights the issue of a how-to guide including excessive learning material, which hinders experienced users trying to achieve a specific goal efficiently.

```text
PROBLEM: How-to guide that explains everything in detail 
and includes background material.

Result: Experienced user trying to accomplish a goal has to 
wade through unnecessary explanation. Can't scan quickly.

Solution: Remove explanation, link to learning material, 
assume competence, focus on the goal.
```

--------------------------------

### Listing Options in Reference Documentation

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/reference.md

Examples of listing available options, supported formats, or valid levels in reference documentation.

```plaintext
"Available options: verbose, quiet, debug, trace."
"Supported formats: JSON, YAML, XML."
"Valid log levels: error, warning, info, debug."
```

--------------------------------

### Providing Warnings and Constraints in Reference Documentation

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/reference.md

Examples of warnings and constraints that must be followed when using a feature or command.

```plaintext
"You must initialize the system before connecting."
"You must not modify this value after starting."
"Never use this in production without backup."
```

--------------------------------

### Reference: Database Connection Pool Configuration

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/common-distinctions.md

This example illustrates the format of reference documentation, providing detailed, factual information about specific configuration parameters for database connection pooling.

```markdown
Section: Database Connection Pool Configuration

Parameter: pool_size
Description: Number of connections to maintain in the pool
Default: 10
Type: Integer
Valid range: 1-1000

Parameter: pool_timeout
Description: Maximum time to wait for a connection from the pool
Default: 30 (seconds)
Type: Integer
...
```

--------------------------------

### How-to Guide Heading Hierarchy

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/how-to-guides.md

A typical structure for a how-to guide, outlining the essential sections from main title to troubleshooting.

```markdown
# How to [accomplish specific goal]

## Overview/Context
Brief context about the problem or goal (1-2 paragraphs)

## Prerequisites
What must be true before following this guide

## Steps
1. [First action]
2. [Second action]
...

## Verification
How to confirm the goal was accomplished

## Troubleshooting
Common problems and solutions

```

--------------------------------

### Problem-Focused vs. Tool-Focused Guidance

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/how-to-guides.md

Illustrates the difference between writing guides from a user's problem perspective versus a tool's functionality perspective. Problem-focused guides are more valuable as they align with user needs and goals.

```text
WRONG (tool-focused):
"To turn on the motor, toggle the power switch clockwise."

RIGHT (problem-focused):
"To achieve consistent spindle speed under load, adjust the governor 
proportional to your target RPM, accounting for friction at startup."
```

--------------------------------

### Referencing API Reference from Tutorials

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/reference.md

This snippet illustrates how a tutorial can point users to the reference documentation for detailed parameter information.

```text
"For detailed parameter documentation, see [Reference]."
```

--------------------------------

### Describing Relationships in Reference Documentation

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/reference.md

Examples of describing relationships between components, such as inheritance, overriding, or requirements.

```plaintext
"This class inherits from BaseClass."
"This parameter overrides the default configuration."
"This option requires authentication."
```

--------------------------------

### Configuration Option as Reference

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/common-distinctions.md

Provides precise, factual details for a configuration option, suitable for direct lookup during system configuration.

```text
Configuration option: `cache_ttl`

Type: Integer (seconds)
Required: No
Default: 3600
Valid range: 1-86400

Description: Time to live for cached entries. After this 
duration, entries are invalidated.

Example:
cache_ttl=7200
```

--------------------------------

### Example Documentation Structure for Audience Segmentation

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/advanced-topics.md

Illustrates a hierarchical structure for organizing documentation tailored to different audiences like administrators and developers, with a separate section for shared content.

```text
Documentation
├─ For Administrators
│  ├─ Tutorials
│  ├─ How-to guides
│  ├─ Reference
│  └─ Explanation
├─ For Developers
│  ├─ Tutorials
│  ├─ How-to guides
│  ├─ Reference
│  └─ Explanation
└─ Shared
   ├─ Concepts
   ├─ Glossary
   └─ FAQs
```

--------------------------------

### Stating Facts in Reference Documentation

Source: https://github.com/evildmp/diataxis-documentation-framework/blob/main/_autodocs/reference.md

Examples of factual statements used in reference documentation to describe parameters, inheritance, or requirements.

```plaintext
"The timeout parameter specifies how many seconds before abandoning a connection."
"Configuration is inherited from parent classes."
"This command requires administrative privileges."
```