easysdd-guidedoc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

easysdd-guidedoc

代码解决问题，文档让别人能用它解决问题。spec 文件记录了"做了什么、为什么这么做"，但下游开发者和终端用户不需要、也不应该读 spec——他们需要的是面向自己角色的、可发布的指南。

guidedoc 就是从 spec 和代码出发，写成读者真正能用的指南。

Code solves problems, and documentation enables others to use it to solve problems. Spec files record "what was done and why it was done", but downstream developers and end users don't need to, and shouldn't, read specs —— they need role-specific, publishable guides tailored to them.

guidedoc starts from specs and code to create guides that readers can actually use.

两条轨道

Two Tracks

轨道	目标读者	典型内容	输出路径
`dev-guide`	贡献者、集成方、下游开发者	本地 setup、架构解说、API 说明、扩展方式	`docs/dev/{slug}.md`
`user-guide`	终端用户	功能概述、操作步骤、概念解释、常见问题	`docs/user/{slug}.md`

轨道选择从"谁读"出发，不从"写的是接口还是步骤"出发——同一个 feature 经常需要两份：API 变化进 dev-guide，对应的用户操作进 user-guide。

路径
docs/dev/
和
docs/user/
是默认约定，项目已有自己的 docs 结构就以项目为准——开始前先确认。

Track	Target Readers	Typical Content	Output Path
`dev-guide`	Contributors, integrators, downstream developers	Local setup, architecture explanation, API description, extension methods	`docs/dev/{slug}.md`
`user-guide`	End users	Feature overview, operation steps, concept explanations, FAQs	`docs/user/{slug}.md`

Choose the track based on "who will read it", not "whether it's about interfaces or steps" —— the same feature often requires two versions: API changes go into dev-guide, and corresponding user operations go into user-guide.

The paths
docs/dev/
and
docs/user/
are default conventions; follow the project's existing docs structure if it has one —— confirm this before starting.

触发时机

Trigger Timing

情境	说明
feature-acceptance 结束	按 `easysdd/reference/shared-conventions.md` 主动推：方案 doc 第 2 节（接口契约）有变更就问"需要更新 dev-guide 吗？"，方案 doc 第 1 节（用户可见行为）有变更就问"需要更新 user-guide 吗？"
用户主动触发	"写文档"、"guidedoc"、"补一份开发者指南"
onboarding 完成后	新仓库可触发本工作流补全基础文档骨架

主动推送一句话即可，用户说"不用"就别再提——多次推会让用户觉得 AI 在加戏。

Scenario	Description
After feature-acceptance completion	Proactively push according to `easysdd/reference/shared-conventions.md` : If section 2 (interface contract) of the solution doc has changes, ask "Do we need to update the dev-guide?"; if section 1 (user-visible behavior) has changes, ask "Do we need to update the user-guide?"
Active trigger by user	"Write documentation", "guidedoc", "Add a developer guide"
After onboarding completion	This workflow can be triggered for new repositories to complete the basic documentation skeleton

Only send a single proactive push message; if the user says "no", don't bring it up again —— repeated pushes will make the user feel the AI is overstepping.

涉及路径

Involved Paths

guidedoc 产物不在
easysdd/
下——指南是面向外部读者的可发布产物，和 spec 工件分开。

dev-guide →
```
docs/dev/{slug}.md
```
user-guide →
```
docs/user/{slug}.md
```

文件命名

{slug}.md

（英文小写 + 连字符，无日期前缀）——指南持续更新，按主题管理而不是按创建日期。

检索已有指南：

python easysdd/tools/search-yaml.py --dir docs/dev --filter doc_type=dev-guide --filter status=current
python easysdd/tools/search-yaml.py --dir docs/user --filter doc_type=user-guide --filter component={feature-slug}

guidedoc outputs are not under
easysdd/
—— guides are publishable products for external readers, separated from spec artifacts.

dev-guide →
```
docs/dev/{slug}.md
```
user-guide →
```
docs/user/{slug}.md
```

File naming uses

{slug}.md

(lowercase English + hyphens, no date prefix) —— guides are continuously updated and managed by topic rather than creation date.

Search existing guides:

python easysdd/tools/search-yaml.py --dir docs/dev --filter doc_type=dev-guide --filter status=current
python easysdd/tools/search-yaml.py --dir docs/user --filter doc_type=user-guide --filter component={feature-slug}

YAML frontmatter

yaml

---
doc_type: dev-guide | user-guide
slug: {英文描述，连字符分隔}
component: {关联的模块名或 feature slug}
status: draft | current | outdated
summary: {一句话描述此文档涵盖什么}
tags: []
last_reviewed: YYYY-MM-DD
---

status

三态：

```
draft
```
：初稿待 review
```
current
```
：当前有效
```
outdated
```
：对应代码已变，文档没跟上（保留原文，标记后推送更新）

yaml

---
doc_type: dev-guide | user-guide
slug: {English description, hyphen-separated}
component: {Associated module name or feature slug}
status: draft | current | outdated
summary: {One-sentence description of what this document covers}
tags: []
last_reviewed: YYYY-MM-DD
---

Three states for

status

```
draft
```
: Initial draft pending review
```
current
```
: Currently valid
```
outdated
```
: Corresponding code has changed, but the document hasn't been updated (keep the original text, mark it and push for updates)

文档格式

Document Format

dev-guide 正文结构

dev-guide Body Structure

markdown

undefined

markdown

undefined

概述

Overview

一段话描述功能定位和适用场景。

A paragraph describing the feature's positioning and applicable scenarios.

前置依赖

Prerequisites

集成此模块所需的环境、依赖或配置（如有）。

Environments, dependencies, or configurations required to integrate this module (if any).

快速上手

Quick Start

最小可运行示例。代码优先，文字辅助。

Minimum runnable example. Code first, text as supplementary.

核心概念

Core Concepts

（可选）理解接口/API/模块行为所需的关键术语和设计决定。

(Optional) Key terms and design decisions needed to understand the behavior of the interface/API/module.

接口参考

Interface Reference

主要 API、配置选项、事件、钩子。表格或逐项列举。

Main APIs, configuration options, events, hooks. Listed in tables or item by item.

常见场景

Common Scenarios

2-4 个实际使用场景的代码示例，覆盖 happy path 和常见边界。

2-4 code examples of actual usage scenarios, covering happy paths and common boundaries.

已知限制与注意事项

Known Limitations and Notes

（可选）边界、性能考虑、已知 bug 绕过方式。

(Optional) Boundaries, performance considerations, workarounds for known bugs.

功能简介

Feature Introduction

一段话描述功能是什么、解决什么问题。

A paragraph describing what the feature is and what problem it solves.

前置条件

Preconditions

（可选）使用前的前提（账号权限、需先完成的操作等）。

(Optional) Prerequisites before use (account permissions, operations that need to be completed first, etc.).

如何使用

How to Use

步骤化操作。每步一行，关键操作配截图占位（

![描述](./assets/xxx.png)

或注明"此处需截图"）。

Step-by-step operations. One step per line, with screenshot placeholders for key operations (

![Description](./assets/xxx.png)

or note "Screenshot needed here").

常见问题

FAQs

Q: ... A: ...

Related Features

（可选）关联功能的跳转链接或说明。

---

(Optional) Links or descriptions of associated features.

---

工作流步骤

Workflow Steps

Step 1：明确任务范围

Step 1: Clarify Task Scope

确认三件事：

轨道：dev-guide / user-guide / 都要
覆盖范围：新写一份还是更新已有
信息来源：方案 doc 是否已有？已有同 component 的 guide 吗？需要读哪些代码？

Confirm three things:

Track: dev-guide / user-guide / both
Coverage: Write a new one or update an existing one
Information Sources: Is the solution doc available? Are there existing guides for the same component? Which code needs to be read?

Step 2：收集输入

Step 2: Collect Inputs

并行：

读方案 doc（重点：第 0 节术语、第 2 节接口契约、第 1 节用户可见行为）
用
```
search-yaml.py
```
搜 docs/，确认有无同 component 的已有 guide

发现已有 guide 标

outdated

→ 任务定性为更新而非新建。

In parallel:

Read the solution doc (focus: Section 0 Terminology, Section 2 Interface Contract, Section 1 User-Visible Behavior)
Use
```
search-yaml.py
```
to search docs/ to confirm if there are existing guides for the same component

If an existing guide is marked

outdated

→ the task is defined as update rather than create new.

Step 3：起草

Step 3: Draft

按对应轨道结构起草，frontmatter

status

先填

draft

。

约束：

正文只写面向目标读者的内容——不要把方案 doc 里的"实现提示"或内部设计搬过来。读者不同关注点不同，spec 内容混进 guide 会让指南失焦
术语与方案 doc 第 0 节保持一致
代码示例必须来自实际代码，不虚构接口

Draft according to the corresponding track structure, set

status

draft

in the frontmatter first.

Constraints:

Only include content targeted at the intended readers in the body —— do not copy "implementation notes" or internal design from the solution doc directly. Different readers have different focus areas; mixing spec content into guides will make them lose focus.
Keep terminology consistent with Section 0 of the solution doc
Code examples must come from actual code; do not invent fictional interfaces

Step 4：用户 review

Step 4: User Review

展示草稿，逐节确认覆盖范围、描述准确性、是否有读者看不懂的地方。

Show the draft, confirm section coverage, description accuracy, and whether there's content that readers might not understand.

Step 5：落盘

Step 5: Finalize

用户放行后：

写入对应路径
```
status
```
从
```
draft
```
改为
```
current
```
，
```
last_reviewed
```
填当天
更新已有文档时：小修直接在原文件上改，
```
last_reviewed
```
填当天；大改（结构重组、读者定位调整）先把旧文档
```
status
```
改为
```
outdated
```
留作参考，再新写一份

After user approval:

Write to the corresponding path
Change
```
status
```
from
```
draft
```
to
```
current
```
, fill in
```
last_reviewed
```
with the current date
When updating existing documents: Make minor changes directly in the original file, fill in
```
last_reviewed
```
with the current date; for major changes (restructuring, adjusting reader positioning), first mark the old document as
```
outdated
```
for reference, then write a new one

与其他工作流的关系

Relationship with Other Workflows

来源	关系
`easysdd-feature-acceptance`	验收后按 `shared-conventions.md` 主动推：接口变更推 dev-guide，用户可见行为变更推 user-guide
`easysdd-feature-design`	方案第 2 节是 dev-guide 主要信息源；第 1 节是 user-guide 主要信息源
`easysdd-onboarding`	新仓库接入后可补全基础文档骨架
`easysdd-architecture-check`	检测到 design 与代码不一致时，对应 guide 应同步标 `outdated`
`easysdd-decisions`	dev-guide 引用的技术选型应来自 decisions，不独立发明
`easysdd-tricks`	dev-guide 用法示例若与 tricks 重合，交叉引用而不重复写
`easysdd-libdoc`	guide 引用 libdoc 条目做详细参考；libdoc 是零件参考，guidedoc 是任务教程

Source	Relationship
`easysdd-feature-acceptance`	After acceptance, proactively push according to `shared-conventions.md` : Push dev-guide for interface changes, push user-guide for user-visible behavior changes
`easysdd-feature-design`	Section 2 of the solution is the main information source for dev-guide; Section 1 is the main information source for user-guide
`easysdd-onboarding`	After new repository onboarding, complete the basic documentation skeleton
`easysdd-architecture-check`	When inconsistencies between design and code are detected, the corresponding guide should be marked `outdated` synchronously
`easysdd-decisions`	Technical selections referenced in dev-guide should come from decisions; do not invent independently
`easysdd-tricks`	If usage examples in dev-guide overlap with tricks, cross-reference instead of repeating content
`easysdd-libdoc`	Guides reference libdoc entries for detailed references; libdoc is part reference, guidedoc is task tutorial

容易踩的坑

Common Pitfalls

❌ 把方案 doc 里的"实现提示"原文搬进 dev-guide——那是内部 spec
❌ 没检查已有 guide 就新建——可能造成两份内容冲突
❌ guide 写完
```
status
```
还是
```
draft
```
——落盘必须改
```
current
```
❌ 代码已更新，相关 guide 还是
```
current
```
——应标
```
outdated
```
并推送更新
❌ dev-guide 和 user-guide 内容高度重叠——重叠说明其中一份定位有误
❌ 用 guide 存放 spec 信息（不变量、测试约束、根因分析）——这类内容属于
```
easysdd/
```

❌ Copying "implementation notes" from the solution doc directly into dev-guide —— that's internal spec content
❌ Creating a new guide without checking existing ones —— may cause content conflicts
❌ Leaving
```
status
```
as
```
draft
```
after completing the guide —— must change to
```
current
```
when finalizing
❌ Keeping related guides as
```
current
```
after code updates —— should mark as
```
outdated
```
and push for updates
❌ Having highly overlapping content between dev-guide and user-guide —— overlap indicates that one of the guides has incorrect positioning
❌ Storing spec information (invariants, test constraints, root cause analysis) in guides —— such content belongs to
```
easysdd/
```

easysdd-guidedoc

Original

Translation

easysdd-guidedoc

easysdd-guidedoc

两条轨道

Two Tracks

触发时机

Trigger Timing

涉及路径

Involved Paths

YAML frontmatter

YAML frontmatter

文档格式

Document Format

dev-guide 正文结构

dev-guide Body Structure

概述

Overview

前置依赖

Prerequisites

快速上手

Quick Start

核心概念

Core Concepts

接口参考

Interface Reference

常见场景

Common Scenarios

已知限制与注意事项

Known Limitations and Notes

相关文档

Related Documents

user-guide 正文结构

user-guide Body Structure

功能简介

Feature Introduction

前置条件

Preconditions

如何使用

How to Use

常见问题

FAQs

相关功能

Related Features

工作流步骤

Workflow Steps

Step 1：明确任务范围

Step 1: Clarify Task Scope

Step 2：收集输入

Step 2: Collect Inputs

Step 3：起草

Step 3: Draft

Step 4：用户 review

Step 4: User Review

Step 5：落盘

Step 5: Finalize

与其他工作流的关系

Relationship with Other Workflows

容易踩的坑

Common Pitfalls