Dev Guide Generator

Dev Guide Generator

One topic → complete technical tutorial: Through a structured SOP workflow, transform a technical topic into a comprehensive tutorial covering prerequisites, environment setup, core steps, common error troubleshooting, and advanced topics — all accompanied by a cheatsheet.

Quick Start

The user simply provides a technical topic or operational goal, and the Agent automatically generates a complete tutorial following this workflow:

User: Help me write a Docker beginner's tutorial
Agent: [Outputs complete technical tutorial + Cheatsheet following the SOP workflow]

SOP Workflow

Phase 1: Topic Scoping & Audience Analysis

Goal: Define the tutorial's technical subject, target audience, and scope boundaries.

Steps:

1. Parse the topic: Identify the core technology, operational goals, and expected deliverables from the user's input
2. Ask clarifying questions (up to 4 key questions):
   • What is the target audience's technical level? (Complete beginner / Some experience / Experienced developer)
   • What operating system will the reader be using? (macOS / Windows / Linux / Any)
   • What should the reader be able to do after completing the tutorial? (Specific deliverable)
   • Are there any version or tech stack constraints?
3. If the user asks to skip clarification, proceed with these default assumptions:
   • Audience: Has basic programming experience but is unfamiliar with the topic technology
   • Environment: Cover both macOS and Linux (note Windows differences where necessary)
   • Goal: Be able to independently complete a minimal working example

Output: Tutorial metadata summary (topic, audience, objective, scope — no more than 150 words)

Phase 2: Prerequisites

Goal: List all knowledge and tools the reader needs before starting this tutorial, ensuring there are no knowledge gaps.

Steps:

1. Dependency analysis:

   • List all technical concepts involved in this tutorial
   • For each concept, determine whether it should be "explained within the tutorial" or "assumed as prior knowledge"
   • Decision rule: If explaining it would digress more than 200 words from the main topic, classify it as a prerequisite

2. Prerequisites checklist:

   • Categorize into "Must know" and "Nice to know" tiers

   • Attach a one-line explanation for each: "why you need it"

   • Format:

     **Must know**:
     - [Concept]: [Why you need it] (Recommended resource)
     
     **Nice to know**:
     - [Concept]: [What aspects of the tutorial it relates to]

3. Self-check rules:

   • If prerequisites exceed 5 items, consider narrowing the tutorial scope or splitting into a series
   • Every prerequisite must have a publicly available learning resource

Output: Tiered prerequisites checklist

Phase 3: Environment Setup

Goal: Provide a reproducible environment configuration path so the reader is fully set up before starting the core steps.

Steps:

1. Environment inventory: List all tools to install/configure with recommended versions

   • Format: Tool name Version requirement (e.g., >= x.y) | Purpose
   • Clearly distinguish "required" from "optional" installations

2. Installation steps: Provide commands for each operating system

   • Precede each command with a one-line explanation of what it does

   • Use only officially recommended methods or mainstream package managers

   • Format:

     **macOS**:
     # Install xxx (via Homebrew)
     brew install xxx
     
     **Linux (Ubuntu/Debian)**:
     # Install xxx (via apt)
     sudo apt update && sudo apt install -y xxx

3. Environment verification: Provide a verification command and expected output after each tool installation

   • Format:

     # Verify installation
     xxx --version
     # Expected output: xxx x.y.z

4. Self-check rules:

   • All installation commands must come from official documentation or mainstream package managers — no third-party scripts
   • Never include real API keys, passwords, tokens, or other sensitive values
   • When configuration files are involved, use placeholders (e.g., YOUR_API_KEY) and explain how to obtain the real value

Output: OS-specific installation and configuration guide + verification commands

Phase 4: Core Steps

Goal: Walk the reader through the core operations in a progressive structure, where each step can be independently verified.

Steps:

1. Step planning:

   • Break the entire operation into 5–10 steps (each focused on one sub-goal)
   • Order steps strictly by dependency
   • Each step includes: step number, title, and objective statement

2. Step writing format:

   #### Step N: [Step Title]
   
   **Objective**: [What state is achieved after this step]
   
   **Actions**:
   [Code block or operational instructions]
   
   **Explanation**:
   - [Line-by-line or section-by-section explanation of key parts]
   
   **Verification**:
   [What command to run / what result to check to confirm success]
   Expected output: [Specific expected result]

3. Writing guidelines:

   • Code blocks must specify the language (e.g., bash, python)
   • Placeholders use ALL_CAPS_WITH_UNDERSCORES format (e.g., YOUR_PROJECT_NAME) and are explained on first occurrence
   • Each code block should not exceed 30 lines; split and explain in sections if longer
   • Use relative file paths; state the project root directory at the beginning
   • Every step must end with a verification section

4. Progressive complexity:

   • Steps 1–3: Minimal runnable example (Hello World level)
   • Middle steps: Gradually introduce real-world features
   • Final 1–2 steps: Combine everything into a complete example

Output: Numbered step list, each containing actions + explanation + verification

Phase 5: Troubleshooting

Goal: Anticipate problems the reader may encounter and provide a direct path from error message to solution.

Steps:

1. Error collection: Based on the technical topic, list the 5–8 most common error scenarios

   • Sources: Environment misconfiguration, version incompatibilities, permission issues, typos, network problems, etc.

2. Error entry format:

   **Error N: [Error message summary]**
   
   Full error message:
   [Actual error output]
   
   Cause: [One-sentence explanation of why this error occurs]
   
   Solution:
   [Specific fix commands or steps]
   
   Verify the fix:
   [What to run to confirm the issue is resolved]

3. Writing guidelines:

   • Error messages must be real (do not fabricate error messages)
   • Solutions must be actionable — avoid vague advice like "check your configuration"
   • If an error has multiple possible causes, list them from most to least likely
   • For permission-related issues, explain why the permission is needed rather than jumping to sudo or chmod 777

4. Self-check rules:

   • Solutions must not include operations that could create security risks (e.g., chmod 777, disabling firewalls)
   • Never advise the reader to disable security features to "fix" a problem

Output: Structured troubleshooting table