docs-how-to-guide

name	docs-how-to-guide
description	Write a how-to guide on a specific topic in a ZIO library. Use when the user asks to write a guide or walkthrough that teaches how to accomplish a concrete goal using the library's data types and APIs.
argument-hint	[guide title or topic description]
allowed-tools	Read, Glob, Grep, Bash(sbt:*), Bash(sbt gh-query*)

Write a How-To Guide

Write a comprehensive, goal-oriented how-to guide for the ZIO library being documented.

Guide Topic

$ARGUMENTS

If no topic appears above (or the literal text $ARGUMENTS is shown), ask the user what guide they want to write before proceeding. Do not invent a topic.

Overview: What Makes a Good How-To Guide

A how-to guide is goal-oriented — it helps the reader accomplish a specific, concrete task. It is neither a reference page (which documents an API exhaustively) nor a tutorial (which teaches concepts step by step). A how-to guide assumes the reader already has basic familiarity and wants to get something done.

Key properties of a good how-to guide:

• Starts with a clear goal: The reader knows exactly what they will accomplish by the end.
• Shows a practical, realistic example: Not toy examples — something close to what a real user would build.
• Introduces types and APIs only as needed: No exhaustive API coverage; only what serves the goal.
• Builds incrementally: Each section builds on the previous one, progressing toward the goal.
• Ends with a working result: The reader has something functional at the end.

---

Step 1: Deep Research — Understand the Topic Landscape

Before writing a single word, you must build a complete mental model of every type, method, pattern, and integration point relevant to the guide topic. This is the most critical step.

For the source research procedure (finding source files, tests, examples, and GitHub history), use the docs-research skill. It covers steps 1a–1d: identifying core data types, supporting types, real-world patterns, and GitHub history search.

1e. Answer These Research Questions

Before proceeding to writing, you must be able to answer every one of these questions. Write the answers down (internally) as they will directly inform the guide structure:

About the problem:

1. What specific problem does this guide solve? State it concretely, not abstractly.
2. What happens if the reader does NOT have this solution? (boilerplate, runtime errors, maintenance burden, etc.)
3. How would the reader attempt to solve this without this library? Can you show a "before" code example?
4. Is this a common pain point that many developers face, or a niche scenario? (This affects how much you need to motivate the problem.)

About the goal:

5. What concrete thing will the reader have built/accomplished by the end of this guide?
6. What is the minimal set of types and operations needed to achieve this goal?
7. What are the key decision points where the reader must choose between approaches?
8. What are the common mistakes or pitfalls a reader might hit?

About the types involved:

9. For each core type: What is it, in one sentence? What role does it play in achieving the goal?
10. What is the dependency/composition order? (e.g., "First define a Schema, then derive a Codec, then use a Format")
11. Which factory methods and constructors will the reader actually use?
12. What type class instances are derived automatically vs. must be created manually?

About the narrative arc:

13. What is the simplest possible starting point? (The "hello world" for this goal)
14. What layers of complexity can be added incrementally? (e.g., start with a flat record, then add nesting, then add collections, then add custom types)
15. Where should you pause to show intermediate results? (e.g., print output, show JSON, demonstrate validation)
16. What is the natural ending point — the "complete" version?

About the ecosystem:

17. What imports does the reader need?
18. What sbt dependencies are required?
19. Are there Scala 2 vs. Scala 3 differences the reader should know about?
20. Does this integrate with other ZIO libraries (ZIO HTTP, ZIO Streams, etc.)?

---

Step 2: Design the Guide Structure

Based on your research answers, design the guide's section structure before writing. A how-to guide follows this general skeleton:

Structural Template

1. Introduction (what we're building and why)
2. The Problem (what problem we're solving, why it matters, example of the pain)
3. Prerequisites (dependencies, imports, assumed knowledge)
4. The Core Model (define the domain types we'll work with)
5. Step-by-step sections (each building toward the goal)
   - Each section: brief explanation → code → result/output
6. Putting It Together (the complete working example)
7. Running the Examples (how to clone the repo and run companion code)
8. Going Further (optional: variations, advanced techniques, links)

Section Design Rules

• Each section has exactly one new concept or capability. If you find yourself explaining two unrelated things in one section, split it.
• Every section has at least one code example. No section should be pure prose.
• Sections should be independently valuable where possible — a reader skimming should be able to jump to a section and get value.
• Use progressive disclosure: Start with the simplest version that works, then add complexity. Do not front-load all the types and theory.
• Limit scope aggressively. A guide about "writing a query DSL" should not become a guide about "everything you can do with Schema." Stay on topic.

Narrative Planning

Plan the running example that threads through the guide:

1. Choose a realistic domain — e.g., an e-commerce system, a blog platform, a user management system. Pick something readers can relate to.
2. Define 3-5 domain types that demonstrate the features you need. Start simple (1-2 fields) and grow them as the guide progresses.
3. Plan the "show moments" — points where you print, serialize, validate, or otherwise demonstrate that the code works. These are crucial for reader confidence.

---

Step 3: Write the Guide

File Location and Frontmatter

Place the file in docs/guides/ directory:

---
id: <kebab-case-id>
title: "<Guide Title>"
---

The id must match the filename (without .md).

Writing the Sections

Introduction

Start with a single paragraph stating:

• What the reader will accomplish (the goal)
• Why this is useful (the motivation)
• What approach we will take (the strategy, in one sentence)

Then include a brief outline of what the guide covers — a bulleted list or a table of contents if the guide is long (more than 6 sections).

Do NOT start with theory or type definitions. Start with the promise of what the reader will build.

Pattern:

In this guide, we will build [concrete thing] using [key library types]. By the end,
you will have [tangible result] that [does something useful].

We'll take an incremental approach: starting with [simple version], then adding
[feature], [feature], and [feature] until we have a complete [thing].

The Problem

Immediately after the introduction, include a dedicated section that clearly states the problem this guide solves. This section has three parts:

1. State the problem concretely. Describe the specific pain point, challenge, or gap that motivates this guide. Be precise — "serializing data is hard" is too vague; "you need to serialize a deeply nested case class hierarchy to JSON without writing boilerplate encoders for each type" is concrete.

2. Explain why it matters. Connect the problem to real consequences the reader cares about: wasted time, runtime errors, maintenance burden, boilerplate explosion, fragile code, etc. Help the reader feel the weight of the problem so the solution feels earned.

3. Show examples of the problem. When possible, include a short code example (or a description of a scenario) that makes the problem tangible. Show what the reader's code looks like without the solution — verbose, error-prone, or brittle. This creates a clear "before/after" contrast with the rest of the guide.

Pattern:

## The Problem

[1-2 sentences naming the specific problem.]

[1-2 sentences explaining why this matters — what goes wrong if you don't solve it.]

For example, consider [a realistic scenario]:

​```scala
// Without this library, you might write something like this:
// [show the painful/boilerplate/fragile approach]
​```

This approach [breaks down when X / doesn't scale because Y / is error-prone because Z].

In this guide, we'll solve this by [brief preview of the library's approach].

Guidelines for this section:

• Keep it to 1-2 short paragraphs plus an optional code example. Do not over-explain.
• The code example should be plain scala (no mdoc) since it shows non-ZIO-Blocks code or pseudocode.
• If the problem is architectural or conceptual (not easily shown in code), use a concrete scenario description instead of a code example. For instance: "Imagine you have 40 case classes representing your API schema and you need to keep JSON codecs, database mappings, and OpenAPI specs in sync."
• The problem section naturally sets up the rest of the guide. The reader should finish this section thinking "yes, I have this exact problem" and be motivated to read on.

Prerequisites

A short section listing:

• sbt dependency (the libraryDependencies line)
• Base imports that will be used throughout (put in an mdoc:silent block so subsequent blocks can use them)
• Assumed knowledge — what the reader should already know (link to relevant reference pages)

Core Model / Domain Setup

Define the domain types the guide will use. Use an mdoc:silent block so subsequent sections can reference these types:

case class User(name: String, email: String, age: Int)
case class Order(id: Long, userId: Long, items: List[Item])
case class Item(name: String, price: Double, quantity: Int)

Briefly explain why you chose these types and how they relate to the goal.

Step-by-Step Sections

For each section:

1. Lead with 1-3 sentences explaining what we're doing and why.
2. Show the code in an appropriate mdoc block.
3. Show the result — if the code produces output, use mdoc (not mdoc:compile-only) to show the evaluated result. If it's a type-level or structural result, add a comment showing what was created.
4. Add a brief "what happened" explanation if the code does something non-obvious.
5. Use admonitions for tips, warnings, or gotchas:

:::tip
This pattern also works for [related use case].
:::

:::warning
Do not [common mistake] — it will [bad consequence].
:::

Putting It Together

Near the end, show the complete working example that combines everything from the guide into a single cohesive block. This should be a mdoc:compile-only or mdoc:silent:reset + mdoc:compile-only block that a reader could copy-paste and run.

Running the Examples

Follow the "Running the Examples" section template from the docs-examples skill. It provides the exact Markdown pattern to use in your guide, substituting the correct <packagename> and example object names.

Going Further (Optional)

If relevant, end with:

• Links to related reference pages for deeper API coverage
• Variations or extensions the reader might try
• Links to other guides that build on this one

Writing Style Rules

See the docs-writing-style skill for universal prose style, Scala version rules, and code block conventions.

Compile-Checked Code Blocks with mdoc

See the docs-mdoc-conventions skill for the complete mdoc modifier table, key rules, and the "For How-To Guides (Progressive Narrative)" section which explains the recommended modifier sequence for guides specifically.

Docusaurus Admonitions

See the docs-mdoc-conventions skill for admonition syntax and usage guidelines.

---

Step 4: Create Companion Examples

Use the docs-examples skill to create companion examples. It covers all aspects: directory structure, file templates, compilation verification, and the lint check procedure. Follow steps 4a–4f exactly as documented in that skill.

---

Step 5: Verify Mdoc Compilation

Before integrating, verify that all code examples in the guide compile:

sbt "docs/mdoc --in docs/guides/<guide-name>.md"

Important: Always use --in <file.md> to compile only this file. Never use bare sbt docs/mdoc without --in — it recompiles all documentation (~90 seconds).

Fix any compilation errors before proceeding to integration.

---

Step 6: Integrate

See the docs-integrate skill for the complete integration checklist (sidebars.js, index.md, cross-references, link verification).

Additional notes for how-to guides:

• Place the file in docs/guides/ directory.
• In sidebars.js, add under a "Guides" category (create it if absent).
• Cross-reference: add links from any related reference pages (e.g., if the guide uses Schema, add a "See also" link from docs/reference/schema.md).

---

Step 7: Review Checklist

Before submitting, work through the checklist in CHECKLIST.md.