SuperAPI AI Directory

cs-doc-tutorial

General & other

View repository

Updated 10-15 23:41

About this skill

cs-doc-tutorial

Must-read before starting

Before making any judgment or taking any action, first run the CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not substitute by reading external AI entry points (see .codestable/reference/execution-conventions.md)。

Code solves the problem; documentation lets others use it to solve the problem. The spec records "what was done and why it was done this way," but downstream developers and end users do not need to—and should not—read the spec; they need publishable guides oriented to their own roles. doc-tutorial starts from the spec and code and writes 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, common questions docs/user/{slug}.md

Track selection starts from "who reads it"—the same feature often needs two: API changes go into dev-guide, and the corresponding user operations go into user-guide.

Path docs/dev/ and docs/user/ are default conventions; if the project already has its own docs structure, follow the project—confirm before starting.


Trigger timing

Situation Description
feature-acceptance ends Proactively suggest: if section 2 (interface contract) of the proposal has changes, ask "Do you need to update dev-guide?"; if section 1 (user-visible behavior) has changes, ask "Do you need to update user-guide?"
User proactively triggers "Write docs," "doc-tutorial," "add a developer guide"
After onboard completes A new repository can trigger completion of the basic documentation skeleton

One proactive suggestion sentence is enough; if the user says "no need," do not mention it again—repeated suggestions make users feel the AI is adding drama.


Involved paths

doc-tutorial outputNot under .codestable/ below—guides are publishable artifacts for external readers, separate from spec artifacts.

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

File naming {slug}.md(English lowercase hyphenated,no date prefix)—guides are continuously updated and managed by topic.

Search:

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

YAML frontmatter

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

status three states:draft pending review;current currently valid;outdated corresponding code has changed but the documentation has not kept up (keep the original text, mark it, then push an update).


Documentation format

dev-guide body structure

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

## 前置依赖
集成此模块所需的环境、依赖或配置(如有)。

## 快速上手
最小可运行示例。代码优先文字辅助。

## 核心概念
(可选)理解接口 / API / 模块行为所需的关键术语和设计决定。

## 接口参考
主要 API / 配置选项 / 事件 / 钩子。表格或逐项列举。

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

## 已知限制与注意事项
(可选)边界、性能考虑、已知 bug 绕过方式。

## 相关文档
关联的 user-guide、方案 doc、相关 ADR 或外部参考。

user-guide body structure

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

## 前置条件
(可选)使用前的前提(账号权限、需先完成的操作)。

## 如何使用
步骤化操作。每步一行,关键操作配截图占位(`![描述](./assets/xxx.png)` 或注明"此处需截图")。

## 常见问题
Q: ...
A: ...

## 相关功能
(可选)关联功能跳转链接或说明。

Workflow steps

  1. Clarify task scope—track (dev / user / both) + coverage scope (new writing or update) + information sources (does the proposal doc already exist? Is there an existing guide for the same component? Which code needs to be read?)
  2. Collect inputs—read the proposal doc (focus on section 0 terminology, section 2 interface contract, section 1 user-visible behavior) + search-yaml.py search docs/ to confirm whether an existing guide exists. If an existing guide is found, mark it outdated → classify the task asUpdate
  3. Draft—draft according to the corresponding track structure, frontmatter status: draft. Constraints: only write content aimed at the target readers—do not copy the "implementation hints" or internal design from the solution doc; terminology must be consistent with Section 0 of the solution doc; code examples must come from actual code and must not fabricate interfaces
  4. user review—show the draft, confirm section by section the coverage / accuracy of descriptions / whether there is anything readers cannot understand
  5. write to disk—after the user approves: write to the path;status: current + last_reviewed same day; when updating existing documents, make minor edits directly, and for major changes (structural reorganization / adjustment of reader targeting) first keep the old document status: outdated for reference before writing a new one

Relationship with other workflows

Source Relationship
cs-feat-accept proactively push after acceptance: push interface changes to dev-guide, and user-visible changes to user-guide
cs-feat-design Section 2 of the solution is the main information source for dev-guide; Section 1 is the main information source for user-guide
cs-onboard after a new repository is onboarded, the basic documentation skeleton can be completed
cs-keep if the technical choices / usage examples referenced by dev-guide have already been accumulated in compound, cross-reference them instead of writing them again
cs-doc-api guide references doc-api entries for detailed reference; doc-api is component reference, doc-tutorial is task tutorial

Common pitfalls

  • copying the original text of the "implementation hints" from the solution doc into dev-guide—that is an internal spec
  • creating a new one without checking existing guides—there may be two conflicting copies
  • after writing status still draft—writing to disk must change current
  • the code has been updated but the relevant guide is still current—should be marked outdated and push the update
  • dev-guide and user-guide content overlap heavily—one of them has the wrong positioning
  • using guide to store spec information (invariants / test constraints / root cause analysis)—this type of content belongs in .codestable/