How to Write a Guide

Guides enhance understanding of a specific topic and provide context to the reader. This cookbook outlines the steps to create effective and engaging guide in line with the Divio Documentation System.

Prerequisites

• A good understanding of the topic you're explaining.
• Familiarity with the Divio Documentation System.

Goal

To craft a guide that explains a concept, process, or decision clearly, making it understandable to the intended audience.

Step 1: Identify Your Audience

Understanding who you are writing for is crucial. Different audiences require different levels of detail and technical language.

1. Define the Audience: Determine their level of expertise and background knowledge.
2. Tailor Your Content: Adjust the complexity of your explanation to suit your audience's needs.

Step 2: Define the Scope of Your Explanation

Clearly outline what your document will cover to stay focused and relevant.

1. Choose a Focused Topic: Select a specific concept, process, or decision to explain.
2. Set Boundaries: Decide what you will include and what falls outside the scope of this document.

Step 3: Structure Your Document

A well-organized structure is key to delivering your explanation effectively.

1. Introduction: Start with an overview that states what you will explain and why it matters.
2. Background Information: Provide any necessary context or background to understand the topic.
3. The Explanation: Break down the subject into manageable parts and explain each clearly.
4. Visual Aids: Use diagrams, charts, or illustrations if they help clarify complex ideas.
5. Examples: Incorporate examples to illustrate your points and make abstract concepts more concrete.

Step 4: Write Clearly and Concisely

The success of a guide lies in how well it communicates complex ideas in an understandable way.

1. Use Plain Language: Avoid jargon or, when necessary, clearly define technical terms.
2. Be Concise but Thorough: Cover all relevant aspects of the topic without overwhelming the reader with unnecessary detail.
3. Use Analogies and Metaphors: These can help bridge understanding by relating new concepts to familiar ones.

Step 5: Encourage Further Exploration

A good guide not only clarifies a topic but also stimulates curiosity and further learning.

1. Suggest Further Reading: Offer links to related topics, tutorials, or reference documents.
2. Pose Questions: End with questions or thoughts that encourage the reader to explore the topic further.

Step 6: Review and Revise

Ensure your document is accurate, easy to follow, and engaging.

1. Feedback: Have peers or subject matter experts review your document for clarity and accuracy.
2. Revise: Incorporate feedback to refine and improve your explanation.

Conclusion

Writing a guide is about making complex information accessible and understandable. By following these steps, you can create a document that not only informs but also enlightens your audience, fostering a deeper understanding of the subject matter.

Template

Copy and paste this template into a new document to begin writing a new Reference article.

# Title of the Guide

- Brief overview of the topic.
- Importance of the topic in the broader context.

## Background

- Historical context or background of the topic.
- Key concepts or terms related to the topic.

## Main Discussion

### Subtopic 1

- Detailed discussion on subtopic 1.
- Relevant examples or case studies.

### Subtopic 2

- Exploration of subtopic 2.
- Analysis of implications or effects related to subtopic 2.

## Alternatives and Opinions

- Overview of alternative approaches or viewpoints.
- Discussion on the pros and cons of different options.
- Personal or widely recognized opinions on the matter.

## Contextual Understanding

- How the topic fits into the larger picture.
- Why the topic is relevant to the reader or the field.
- Any significant design decisions, technical constraints, or historical reasons behind current practices.

## Conclusion

- Summary of key points discussed.
- Reflection on the importance of understanding the topic beyond practical applications.
- Invitation for further exploration or discussion.

## See Also

- List of cited works, articles, or documents for further reading.