Simple Docs for Humans and Agents

Primary Goal

• Bias toward simple docs.
• Start with the shortest successful path.
• Preserve original meaning and factual content while reordering for clarity.

Required Output Order

1. Quickstart (always first)
2. Main workflow
3. Configuration/reference tables (when relevant)
4. Alternative paths (only when they are true user/code path alternatives)
5. Extra details at the end inside

   <details><summary>...</summary>...</details>

Approval Gate (Required)

• Before editing any file, show a change preview for approval.
• Use this exact preview structure for each file:
  • Additions
  • Removals
  • Changes
• Show the concrete text to be added, removed, or changed.
• Wait for explicit user approval before applying edits.
• Apply only the approved edits.
• If approval is not granted, do not modify files.

Core Rules

• Optimize for both human readers and agent readers.
• Maximize copy-paste command snippets.
• Prefer short sections and concise language.
• Use Markdown tables when information is structured.
• Use Mermaid diagrams when they improve understanding of flow or architecture.
• Avoid unnecessary sections.
• Avoid "Optional" sections unless they represent an actual alternate path.
• Put superfluous/background material at the end.
• Add "Code Structure" only when repository layout helps task completion.

Command Block Rules (Strict)

• Do not place comments inside bash code blocks.
• Put labels outside code blocks.

make start_server

make run_command

make start_server
make run_command

Section Defaults

• Quickstart
• Main Workflow
• Configuration
• Code Structure (only if useful)
• Troubleshooting (only for real recurring issues)

Configuration Table Format

APP_ENV

development

API_URL

http://localhost:8000

Details Block Rule

<details>
<summary>Deep dive: request lifecycle</summary>

Detailed explanation here.

</details>

Deliverable

• Return the final output as Markdown (

  .md

  ).
• Keep all important content, but simplify, reorder, and prioritize for quick execution.