nk-documentation-best-practices

NK 文档最佳实践

适用于所有 Naykel 项目的通用文档规则。项目专属技能会扩展这些规则——两者都要遵循；如有冲突，以项目技能为准。

审阅工作流

• 每个新标题都标记为 (review)，直到内容得到确认。
• 更新带有 (review) 的章节时，询问该章节是否完整。
• 确认后：移除 (review) 标签并更新项目状态文件。
• 文档结构达成一致后，即使部分章节仍带有 (review)，也要从导航条目中移除 (wip)。
• 对仍未解决的标题保留 (review)。
• 文档中所有 (review) 标签都移除后，即视为完成。
• 结束文档工作时，指出仍带有 (review) 标签的标题或文档。

通用规则

• 一篇文档，一个任务。 如果某个页面既解释心智模型，又列出所有属性，还展示快速入门内容，就应将其拆分。
• 代码优先。 只有在行为不明显或需要提供背景信息时才添加说明文字。

文档结构

• 每篇文档都以标题和简短的导语开头。
• 将导语写为 <p class="lead">...</p>。
• 导语应说明页面涵盖的内容，以及读者能从中获得什么。
• 内容应具体，不要添加填充内容。
• 不要另设 ## Introduction 章节。

导航管理

• 开始编写尚未列入导航的文档时，将其添加到对应的实际分类中，并在名称后加上 (wip)，以便在开发期间访问。
• 导航标签和章节应尽量精简。只有在文档经过审阅并达成一致后，才恢复结构。

规则文件

回复前请阅读相关规则文件——不要只依赖摘要。

组件文档 → rules/component-docs.md

• 单组件页面
• 多组件页面
• 变体和组件系列