Output to the project's docs/ directory. Core constraint: the code, class names, and paths in the documentation must all come from real files; see Phase 3.
Step 0: Determine which type to do
| User wording | What to do |
|---|---|
| Generate project documentation / newcomer documentation / in-depth understanding of the project (no articles specified) | Generate all, Phase 1 → 2 → 3 → 4 |
| Help me write architecture documentation / only the code walkthrough / write build and debugging | Write only the specified articles; the scope of reading the project can be reduced accordingly |
| The code changed, update the documentation / the documentation is outdated | Read docs/.project-map.md, compare with the current code, and rewrite only the affected articles |
docs/ already has content: first list the existing files and ask the user whether to overwrite, skip the existing ones, or back up to docs.bak/. Do not overwrite directly.
Cases where this skill should not be used: the user wants thesis chapters, project summaries, key issue lists, or resume project descriptions—that is, things for advisors, judges, HR, or leaders to read, and whose format is specified by the other party; use codegen-doc. This skill only handles documentation for new colleagues to read and follow to get started.
Phase 1: Read the project first and record the results
Record to docs/.project-map.md. The paths, class names, and code needed for each later article are all taken from this file.
Read in three steps;do not try to read all source files：
- Look at the outline — directory tree, build and dependency files, README; determine what language is used and what type of project it is
- Look at the skeleton — read the entry file in full, interface and type definitions, and list what each module does
- Follow one complete example through — pick a representative example or feature and trace it from entry to end
How to read, what format to record in, and when you can stop are in reference/explore.md. Finish filling in that template before entering Phase 2, and the glossary must have at least 5 entries.
Phase 2: Decide which articles to write according to the project type
01_architecture.md → 架构：项目长什么样
02_philosophy.md → 思想：为什么这样设计
03_lang_concepts.md → 语言特性：读代码前的准备
04_code_walkthrough.md → 代码导读：跟着真实流程走一遍
05_runtime_model.md → 运行时：并发和生命周期
06_build_guide.md → 构建：怎么编译运行
07_integration_guide.md → 对接：怎么写新功能
08_debug_guide.md → 调试：出问题怎么查
09_design_conventions.md → 规范：怎么设计得更好
The default template leans toward C++-style projects that "need compilation, have multithreading, and have inter-process communication".Projects such as frontends, data scripts, and libraries must replace or skip the corresponding articles according to the comparison table, see reference/project-types.md。
The numbering is fixed; leave blank numbers for skipped ones, do not shift them forward. If 05 is skipped, it is 01,02,03,04,06,07,08,09; for the reason, see project-types.md.
Phase 3: Write
Before pasting code, read that file first
.project-map.md contains only paths, not the original code. Whichever code you want to paste, first Read that file to confirm its current content. References should uniformly include location:src/core/channel.cpp:120-135。
If you do not do this, newcomers will search for a class name that does not exist—worse than having no documentation.
Who it is written for
Newcomers who are just getting in touch with the project. Do not assume they understand the project background, but assume they have basic programming ability.
Required in every article
- Start with a
> 一句话说明这篇解决什么问题 - First say "what it is" → then say "why" → finally say "how to do it"
- Include a comparison (❌ how to write it without the framework vs ✅ how to write it with the framework)
- Pair an abstract concept with an example from everyday life
- End with a quick-reference table or checklist
How to draw diagrams
| What to express | What to use |
|---|---|
| Call relationships, timing, state changes, inheritance between classes | Mermaid |
| Directory trees, layered block diagrams, memory layout | ASCII |
Keep ASCII diagram width within 80 characters; if it exceeds that, it will wrap and become misaligned in Typora and on web pages.
How long
Each article 300–600 lines. Fewer than 300 means it is not dug deep enough; more than 600 means it should be split into sections. Avoid one article being two thousand lines and another being thirty lines.
Wording
Use the same word for the same thing throughout, all according to the glossary in .project-map.md . Calling it a "channel" in one article and a "pipe" in another is where newcomers get stuck most easily.
Do not invent terms. Where plain language can make it clear, do not create a new word for readers to remember.
Do not
- Stock phrases like "as mentioned above" and "in summary"
- Obvious filler that readers already know
- Fabricate code, see the first item above
- Leave a term unexplained the first time it appears
- Not say so when commands and examples have not actually been run—mark the ones that cannot be run with
⚠️ 未验证
Templates for each article:reference/chapters-01-04.md、reference/chapters-05-09.md。
Phase 4: Write the table of contents page, then self-check
- Write
docs/README.md, list all articles, explainwhich articles to read for different purposes, and state the reason for skipped articles. See the template in reference/quality.md - Go through each article against the checklist in quality.md
- Make four things clear to the user: which articles were written and how many lines each has, which articles were skipped and why, what content was marked with
⚠️ 未验证、.project-map.md, and what remains unclear. The last two are the easiest to miss, but they are exactly the basis on which the user judges whether the documentation can be given directly to newcomers