Documentation Authoring Playbook【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skillsUse this playbook when adding or revising repository documentation. Write for future agents and humans who need the shortest path to the right detail level.GoalProduce documentation that:explains one layer of the system clearlyavoids mixing overview, workflow, and low-level constraints into one blobmatches the current repository behaviorpoints readers to the next focused file instead of dumping everything at once1. Choose the right documentation layerBefore editing, decide which layer the content belongs to:overview or navigationworkflow playbookdetailed constraint or referenceexample catalogAPI or framework documentationDo not stuff every fact into a giant summary file.2. Prefer progressive disclosureDefault read order should be:router or overviewone playbookone focused referenceone concrete exampleIf a file tries to do all four jobs at once, split it.3. Keep purpose and audience obviousAt the top of a doc, make it obvious:what this file is forwhen to read itwhat it does not try to coverwhere to go next for deeper detailThis matters more than long introductions.4. Separate workflow from factsKeep these concerns separate:workflow: what to do step by stepconstraints: rules that must holdexamples: which source files to studyarchitecture: where logic lives in the repositoryIf readers need all of them at once, link them together instead of merging them into one monster file.5. Keep examples concretePrefer:one direct exampleone clear counterexampleone pointer to the exact source fileAvoid vague advice that cannot be traced to repository code.6. Preserve repository truthWhen behavior is subtle, derive documentation from the implementation path, not from memory. Typical sources:easyasc/agent/example/kernels/testcases/doc/agent/scripts/If you are not sure, inspect the real code before documenting the rule.7. Keep English documentation in EnglishRepository rule:codes, error messages, and readme files should be written in EnglishIf Chinese documentation also needs updating, keep the English source coherent first, then mirror as needed.8. Update owner docs carefullyIf a repository change affects the documentation map or high-level structure, refresh the owner docs that describe it:README.md,README_CN.mdwhen the top-level documentation entry map changedagent/references/repo-map.mdwhen top-level layout or ownership changeddoc/11_architecture_for_contributors.mdwhen contributor-facing architecture or subsystem ownership changedtestcases/README.mdwhen the test-suite layout or fixture/demo boundary changedIf kernel files are added, update:agent/references/examples/kernel-catalog.mdIf tool files are added or changed, update:agent/scripts/tools_summary.mdagent/references/code-paths.mdif the implementation-path lookup changed9. Prefer replacement-ready migrationWhen restructuring documentation, do not delete older guidance until the new layer is actually usable. A migration is only done when the new route works on its own.Fallback referencesRead these if more detail is needed:README.mdagent/references/repo-map.mddoc/11_architecture_for_contributors.mddoc/doc_cn/【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考