Awesome Docs

Awesome Docs

Keep project knowledge easy to find, check, and update. Choose the document type and path by what the reader needs, and preserve enough context for another person or agent to continue the work without guessing.

Execute the Documentation Task

Use the steps below in order. Keep the working notes in memory or a temporary workspace; do not add a planning dossier to the user's repository for a small edit.

For a one-line todo, these steps can mean reading the existing queue, finding the item, adding the line, and re-reading it. They do not require seven visible sections.

Execution Guide Routing

Read the chosen guide before drafting, not only when the first attempt fails. Read only relevant sections.

Documentation Root and Scope

Use the user-specified location first. A path can identify different things:

• Project root: use its existing documentation layout, defaulting to <project-root>/docs.
• Documentation root, such as docs/team-a: put the requested category beneath it.
• Category or book directory, such as docs/reference or docs/books/camera-geometry: use it directly; do not append the category again.
• Exact file: update that file rather than inventing a parallel document.

For a path outside the active checkout, resolve that target repository and its instructions before editing. If the user names another project without giving its path, resolve that project from known context or ask for its location; do not silently write into the active checkout. Only when neither a target project nor a path is specified, use the current repository root; outside a repository, use the current working directory. Ask one concise question only if the destination remains materially ambiguous.

Respect existing locations such as doc/, design/, or an established book directory. The layout below is the default for new content, not a request to migrate old files. Move or rename existing documents only when the user asks to reorganize them.

Default Directory Layout

<docs-root>/
├── README.md              # navigation, when a collection needs an index
├── architecture/          # system structure and architectural decisions
│   └── adr/               # decision records, when needed
├── books/                 # sustained, chapter-based teaching
│   └── <topic>/
│       ├── README.md      # the book’s single reading entry
│       ├── 00_导读与符号.md  # canonical symbols, abbreviations, and conventions
│       ├── 01_基础模型.md
│       └── figures/
├── reference/             # lookup by API, command, field, or version
│   ├── apis/
│   ├── protocols/
│   ├── schemas/
│   └── configuration/
├── plan/                  # execution design for a defined change
├── roadmap/               # outcomes, milestones, and dependencies
├── todo/                  # living actions, ideas, questions, and risks
├── experiment/            # dated evidence and reproducible results
├── knowhow/               # reusable explanations and operating lessons
└── 常用命令.txt            # only when command capture is requested

Create directories and indexes on demand. A one-line todo does not require eight empty directories, a book scaffold, or a command registry. Add topic subdirectories only when they make a growing collection easier to navigate.

Classification Rules

Classify by the reader’s question and how the content will be maintained, not by keywords alone.

Keep one canonical home for each piece of content. Link related documents rather than copying their tables and conclusions. For example, record a storage decision in an ADR, its rollout steps in a plan, and measured effects in an experiment. A protocol field table belongs in reference; a guide to diagnosing that protocol belongs in knowhow.

After classification, follow the execution guide routing above. The output shapes in references/document-types.md are examples, not a requirement to fill every heading.

File Naming

Use names according to the document’s lifecycle. A date prefix is not required on every Markdown file.

Use the user’s date when supplied; otherwise use the environment date for new dated records. Preserve existing naming conventions unless a rename is requested. Write titles in the project’s language; directory names above are defaults, not a reason to translate established paths.

New Document vs Existing Document

Search for an existing same-topic document before creating one. Update an explicit target or a living architecture page, reference, chapter, roadmap, plan, or todo in place. Keep changes local unless the user asks for a broader rewrite.

Create a new file for a new topic, independently reproducible experiment, or superseding decision. A decision change gets a new ADR and a link from the old one; the current-state architecture overview changes when implementation or deployment is verified. Until then, label the accepted but unimplemented design as a target state. Do not silently rewrite historical results or present proposed architecture as deployed.

For a new incompatible interface version, document the versions side by side if both remain relevant. Avoid date-stamped copies of a reference page that leave readers guessing which one applies.

Todo and Roadmap Maintenance

A roadmap describes outcomes; a plan describes execution; a todo holds the next concrete action. A long list of tasks does not become a roadmap merely because it has dates.

• Use stable item IDs when items will be linked, such as T-014 or an existing issue ID.
• For todos, record type, status, source, content, and next action. Add priority, owner, deadline, or blocker only when known; mark unknowns explicitly rather than inventing assignments or commitments.
• Suggested statuses are open, doing, blocked, done, dropped, and promoted; respect an existing project vocabulary. A blocked item names the blocker and the condition that would unblock it.
• For risks, record impact, trigger or evidence, mitigation, and the next observation. A suspected risk stays a suspicion until evidence supports it.
• For roadmap milestones, record the outcome, acceptance evidence, dependencies, status, and any confirmed target window. Distinguish a target from a promise.
• Keep active items near the top. Preserve completed or dropped items with dates and reasons; do not delete their history as cleanup.
• On promotion, link the todo to its destination plan, roadmap, experiment, architecture decision, or knowhow page, and link back when useful. promoted means moved into another document, not implemented or verified.

Writing Style

Remove AI flavor. Write like an engineer preserving project state for another engineer.

For explanatory prose, connect the question, reasoning, evidence, and conclusion. Reference pages should lead with exact definitions and lookup tables; todos should lead with the action and status. Do not force either into a narrative template.

Prefer:

• direct titles
• short sections
• factual conclusions
• commands and file paths in code formatting
• tables for metrics and comparisons
• bullets for decisions and next steps
• one idea per paragraph
• explicit transitions between background, evidence, and conclusion

Avoid:

• filler openings like "本文旨在"
• inflated summaries like "综上所述"
• generic praise
• vague claims without data
• long paragraphs that mix setup, result, and conclusion
• orphaned details that are not tied back to the main question
• dumping raw logs without explaining what they prove

For explanations and work records, answer the relevant questions:

• What happened?
• Why does it matter?
• What evidence supports it?
• What should be done next?
• Where are the commands, data, or files?

Convert Writing Goals into Operations

When a request says “clear,” “rigorous,” or “beginner-friendly,” translate it into work before drafting:

Use the detailed guide for the actual writing sequence. Do not paste this table into every deliverable.

Post-write Review

After creating or updating any Markdown document, re-read the whole file once as an editor. This is required for all document types, including small updates to an existing file.

Run these checks, correcting failures rather than merely saying the document is clear:

1. Follow the reader path. Re-read the opening and then each section in order. Move a definition or add a prerequisite bridge wherever a section needs an unexplained term. For lookup pages and todos, test finding a field or next action rather than imposing a narrative ending.
2. Trace claims backwards. For each consequential conclusion, locate its evidence, version, and assumptions. Mark unsupported portions as unknown or proposed, and separate historical results from current behavior.
3. Check technical consistency. Recalculate worked examples; compare symbols/units against the ledger; inspect signs, frames, domains, formula references, and approximations. For tables, recompute key counts or totals and verify common comparison units. Report checks not run.
4. Walk an action forwards. On procedural pages, follow a representative success and failure branch on paper. Add an expected observation, stop condition, or rollback where the reader would have to guess. Actually run commands only within the user's task authorization.
5. Check the chosen depth. Use the guide's stop criteria. Remove irrelevant lower-level detail by linking its canonical source; add missing boundaries or section outputs. Preserve relevant evidence rather than trimming to an arbitrary word count.
6. Validate artifacts. Resolve local links and images from the containing file; inspect native-format examples with an available parser; render math/figures in the project's existing preview/export path when available. If no renderer exists, inspect source and report that rendering was not verified.
7. Review the diff. Confirm status/versions and navigation changed together, historical evidence remains intact, and no unrequested move, deletion, publication, or application-code edit slipped in.

Re-read the corrected section with its preceding and following sections. Finish only when applicable checks pass or the remaining uncertainty is explicitly documented.

Final Plain-Language Pass

Run this after the post-write content review, not while collecting facts or building the document structure. Read references/post-write-polish.md and route each document type to the appropriate shuorenhua level and scope.

Skip this pass when the user says 不需要润色, 不要润色, 跳过润色, 按原流程, 保持原样, or gives an equivalent instruction. In that case, finish with the existing Post-write Review above and do not invoke shuorenhua, install it, or apply a substitute style pass.

The two passes are internal. Deliver only the final document unless the user explicitly asks to compare the pre-polish and polished versions.

Paths, Assets, and Moves

When the user requests a move, preserve content and evidence while updating the paths around it. If the user already moved the files, inspect the actual new location and repair references there; do not repeat the move:

1. Record the old-to-new directory mapping. Check for destination collisions before moving files.
2. Update links inside moved documents, links pointing to them, README indexes, image paths, and references in scripts, build defaults, export commands, and deployment configuration where applicable.
3. Check paths from each document’s directory, not only from the repository root. A rename can change both inbound and outbound relative paths.
4. Run available link/build checks and regenerate only the affected derived outputs. Check embedded images are real files rather than unresolved LFS pointers.
5. Keep one editable source. Put combined-book exports, rendered previews, caches, and large intermediate datasets in the project’s existing generated/ignored location, not beside the book as a second maintained manuscript.

Follow repository asset rules, including existing LFS policies. Keep small provenance manifests where useful; a hash identifies a file but does not back it up. Do not delete raw data or historical evidence just because it is not committed. Documentation maintenance alone does not authorize committing, pushing, deploying, installing tools, or publishing data.

Document Templates

Use templates only after executing the relevant guide. references/templates.md contains plan, experiment, and knowhow output shapes; references/document-types.md covers the other categories. Fill them from actual evidence and decisions, not from plausible boilerplate. Omit unused headings.

Common Command Registry

常用命令.txt is for copy-pasteable commands only.

Rules:

• Every command must be one physical line.
• Do not use shell line continuations with \.
• Do not wrap long commands across multiple lines.
• Group related commands under Chinese comment blocks.
• Add a short Chinese explanation before each group so humans can scan the file.
• Avoid duplicate commands unless the new command is a meaningful variant.
• If replacing an existing command, keep the group and update only the relevant line.

If a concrete command group or document-update pattern is needed, read references/examples.md. Do not load that reference for routine updates.

Final Response After Writing

After creating or updating documentation, report only the useful facts:

• created or updated files
• category chosen
• key command or result if relevant
• any skipped or unresolved item

Keep the final response brief. Do not paste the entire document unless the user asks.