easysdd-guidedoc

Original：🇨🇳 Chinese

Translated

Write or update external guide documents for the project —— dev-guide (for contributors / integrators / downstream developers) and user-guide (for end users). The output is stored in the project's docs/ directory, maintained alongside the code, and searchable by search tools. Difference from libdoc: guidedoc is task-oriented ("How to do Y with X"), while libdoc is reference-oriented ("What each part of X looks like"). Trigger scenarios: When the user says "write documentation", "developer guide", "user guide", or proactively push when feature-acceptance is completed.

3installs

Sourceliuzhengdongfortest/easysdd

Added on2026-04-20

NPX Install

npx skill4agent add liuzhengdongfortest/easysdd easysdd-guidedoc

SKILL.md Content (Chinese)

View Translation Comparison →

easysdd-guidedoc

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

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

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 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: {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 Body Structure

markdown

## 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
(Optional) Key terms and design decisions needed to understand the behavior of the interface/API/module.

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

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

## Known Limitations and Notes
(Optional) Boundaries, performance considerations, workarounds for known bugs.

## Related Documents
Associated user-guide, solution doc, architecture doc, or external references.

user-guide Body Structure

markdown

## 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
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: Clarify Task Scope

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: Collect Inputs

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: Draft

Draft according to the corresponding track structure, set

status

to

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: User Review

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

Step 5: Finalize

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

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

❌ 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

NPX Install

Tags

SKILL.md Content (Chinese)

easysdd-guidedoc

Two Tracks

Trigger Timing

Involved Paths

YAML frontmatter

Document Format

dev-guide Body Structure

user-guide Body Structure

Workflow Steps

Step 1: Clarify Task Scope

Step 2: Collect Inputs

Step 3: Draft

Step 4: User Review

Step 5: Finalize

Relationship with Other Workflows

Common Pitfalls