Structuring Your Documentation According to Divio

The Divio Documentation System categorizes documentation into four quadrants: Tutorials, How-to Guides, Explanation, and Reference. Each serves a distinct purpose and targets different user needs. This tutorial provides a practical approach to applying these concepts to your documentation project using Markdown.

Divio's Four Document Types

1. Tutorials: Designed to help users get started. They are learning-oriented and provide a step-by-step process to achieve a broad understanding of the subject.

2. How-to's: Task-oriented guides that aim to solve specific problems. They assume the user has a basic understanding of the subject.

3. Explanation: Understanding-oriented. These sections clarify and explain concepts or processes, providing a deeper insight into the subject.

4. Reference: Information-oriented, including technical descriptions of the machinery, code, APIs, or tools. They are structured for quick reference and easy understanding.

Folder Organization

Managing a structured documentation project using Markdown involves organizing your files and content according to the Divio system's quadrants. Here's how to approach it:

Tutorials

For each tutorial, use a separate Markdown file. Start with an introductory paragraph, followed by a step-by-step guide. Use Markdown headings to organize sections, and list items to outline steps.

# Your First Tutorial

Welcome to your first tutorial. This guide will walk you through the steps to achieve [goal].

## Step 1: [Step Title]

Describe the first step.

## Step 2: [Step Title]

Outline the next step, and so on.

How-To's

In a how-to directory, create Markdown files for each specific task. Begin with a brief introduction to the task, followed by detailed steps, using code blocks and lists where appropriate.

# How to [Task]

This guide will show you how to [accomplish specific task].

## Step 1: [Specific Action]

Provide a detailed description of the action required.

Explanations

Use a explanations directory for deeper insights into concepts. These documents should focus on understanding rather than doing, using paragraphs more than lists.

# Understanding [Concept]

Explain the concept here, why it's important, and its underlying principles.

References

For reference material, such as API documentation or command-line options, create a references directory. Structure these files with headings for each item and tables for parameters or options.

# [API/Tool/Command] Reference

## [Function/Command Name]

Description and usage.

| Parameter | Type | Description |
|-----------|------|-------------|
| param1    | Type | Description |

Conclusion

Using Markdown in VS Code allows for a streamlined process in creating, managing, and maintaining your documentation. This approach ensures that your documentation is well-organized, accessible, and useful to your audience.