ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Continue 项目文档编写规范:面向开发者与 AI 协作的 Documentation Style Guide 实战指南

Continue 项目文档编写规范:面向开发者与 AI 协作的 Documentation Style Guide 实战指南 Continue 项目文档编写规范面向开发者与 AI 协作的 Documentation Style Guide 实战指南【免费下载链接】continueopen-source coding agent项目地址: https://gitcode.com/GitHub_Trending/co/continue导读本文以 Continue开源 AI 编码助手仓库中的 documentation-standards.md 为核心系统讲解这套面向docs/目录的文档风格规范如何用简洁、对话式、可操作的语言撰写技术文档如何组织页面结构与章节标题以及如何统一术语、快捷键与平台差异的写法。读完本文你将掌握一套可直接套用到自己项目文档中的写作标准并能结合 Continue 仓库中真实的.mdx文档与源码如 docs/chat/how-to-use-it.mdx、docs/autocomplete/how-to-use-it.mdx、core/config/理解这些规范背后的工程动机。背景说明Continue 是面向 VS Code 与 JetBrains 的开源编码助手支持 Chat、Edit、Agent、Autocomplete 等模式。其官方文档运行在 Mintlify 平台上因此文档风格与 Mintlify 标准保持高度一致。本文围绕该仓库的文档编写规范展开属于「写作规范类」技术文章聚焦文档工程实践。这份 Style Guide 是什么一个可自动加载的文档规则文件文件的定位与作用域documentation-standards.md并不是一篇普通的 Markdown 笔记而是一个可被 Continue 自动识别并加载的 Rule规则文件。它的 YAML frontmatter 明确声明了适用范围--- globs: docs/**/*.{md,mdx} description: This style guide should be used as a reference for maintaining consistency across all Continue documentation alwaysApply: false ---globs: docs/**/*.{md,mdx}该规则作用于docs/目录下所有.md与.mdx文件也就是 Continue 官方文档的全部内容description一句话说明规则用途——在编写/修改文档时保持风格一致alwaysApply: false不是无条件强制生效而是按需加载通常在涉及docs/**下的文档写作任务时被启用。这与 Continue 的 Rules 机制完全一致。在 docs/customize/rules.mdx 中Rules 被定义为AI coding agent 的护栏guardrails允许你在.continue/rules目录下创建规则文件让 Agent 在 Chat、Edit、Agent 模式下自动检测并应用这些规则。因此这份 Style Guide 实际上是 Continue 团队用自家产品规范自家文档产出的一个范例。在仓库中可以看到.continue/rules/目录下还存放着其他配套规则例如 mintlify-formatting.mdMintlify 组件格式规范、documentation-description-rule.mdfrontmatter 中必须包含 100-160 字符的 description、continue-specificity.md 等它们共同构成了一套完整的文档工程体系。写作基调对话式、直接、以帮助开发者完成任务为目标Style Guide 首先确立了三层写作基调每一层都给出了正面✅与反面❌示例对话式与直截了当Conversational and Direct遵循 Mintlify 文档标准用简单、对话式的语言直奔主题能用简单词就不用术语堆砌像直接对正在使用工具的开发者说话一样写作段落保持精炼、可扫读scannable。原文示例对比✅ You send it a question, and it replies with an answer ❌ The system processes user queries and generates corresponding responses在 Continue 的实际文档中这种对话式风格体现得淋漓尽致。比如 docs/chat/how-to-use-it.mdx 中的这句You send it a task, including any relevant information, and it replies with the text / code most likely to complete the task.这正是用简单语言直接说明、使用第二人称 you、用 it 指代工具/模型的规范落地。有帮助且有指导性Helpful and Instructional聚焦于帮助用户达成目标指令使用主动语态和祈使句imperative mood假设用户希望快速完成任务适当使用 Tip、Warning、Info 等 Admonition 组件来承载提示、警告与补充信息。原文示例对比✅ Press cmd/ctrl L to begin a new session ❌ A new session can be initiated by pressing cmd/ctrl L第一句是祈使句 主动语态直接告诉用户按什么键第二句是典型的被动语态教科书腔是文档写作的大忌。务实且以任务为导向Practical and Task-Oriented强调每个功能能帮助用户完成什么先讲收益和使用场景再深入机制细节让讲解落地到真实世界场景中。例如 docs/ide-extensions/chat/quick-start.mdx 的开头就是先讲价值Chat makes it easy to ask for help from an AI without leaving your IDE.随后才展开具体操作步骤。页面结构五段式内容组织模型Style Guide 规定每个文档页面的组织顺序共五个层次视觉引入Visual Introduction用 GIF 或图片展示功能实际效果。例如 docs/chat/how-to-use-it.mdx 和 docs/autocomplete/how-to-use-it.mdx 都在正文前放置了Frame包裹的功能演示 GIF目的陈述Purpose Statement简要说明这个功能是什么、何时使用。如 docs/autocomplete/how-to-use-it.mdx 的第一句 Autocomplete provides inline code suggestions as you type.分步操作Step-by-Step Instructions清晰、可执行的操作步骤包含键盘快捷键平台差异说明Platform-Specific NotesVS Code 与 JetBrains 需要分别说明时用独立小节分开写进阶技巧Additional Tips高级用法或故障排查补充。这套结构在 Continue 的docs/ide-extensions/、docs/autocomplete/、docs/chat/等目录中均有体现例如 chat quick-start 文档在基础用法之后专门设置了 Pro Tips如 Start Fresh、Be Specific、Iterate小节来承载第五层内容。章节标题Section Headers使用一致的标题层级从 h2##开始每个页面要包含 YAML frontmatter声明title、description、keywords标题采用动词 宾语的动作导向格式如 Type a request and press enter标题保持精炼但有描述性使用 title case标题式大小写。Style Guide 给出的正面示例✅ Highlight code and activate ✅ Accept or reject changes ✅ Switch between different models实际的docs/文件印证了这一点how-to-use-it.mdx中的小节标题如 How to Use AI Chat in Continue for Coding Help、Add Code Context to AI Chat by Highlighting Code都是动作导向的祈使句风格。列表与步骤Lists and Steps有先后顺序的步骤用有序列表numbered lists特性列表或选项用无序列表bullet points列表项保持结构平行parallel动作项以动词开头。技术写作标准代码、快捷键、交叉引用与平台差异代码与键盘快捷键Code and Keyboard Shortcuts行内代码元素使用反引号键盘快捷键格式统一为cmd/ctrl L这种写法必须同时给出 Mac/Windows/Linux 的快捷键配置示例用代码块展示并带正确的语法高亮。在 Continue 文档中键盘快捷键通常写成cmd/ctrl LVS Code或cmd/ctrl JJetBrains一次覆盖 Mac 的cmd与 Windows/Linux 的ctrl。例如 docs/ide-extensions/chat/quick-start.mdx 中分别列出了两个平台的快捷键说明。更精细的写法是使用kbd组件例如 docs/customize/deep-dives/configuration.mdx 中Open the sidebar by pressingcmd/ctrlL(VS Code) orcmd/ctrlJ(JetBrains)交叉引用Cross-References用描述性的锚文本链接到相关章节使用指向其他文档页面的相对链接格式descriptive text。Continue 文档中大量使用这一规范例如 docs/customize/prompts.mdx 中的 Learn more in the prompts deep dive以及 docs/customize/rules.mdx 中的 Learn more in the rules deep dive, and viewrulesin the YAML Reference。平台差异Platform Differences只要适用就必须同时覆盖 VS Code 和 JetBrains用清晰的子标题分隔平台专属说明两者都涉及时长先写更常见的平台通常是 VS Code。这也解释了为什么 Continue 文档中大量出现 VS Code / JetBrains 双平台分列的结构例如 chat quick-start 文档中 How to Include Code Context 一节就分列了两个平台的快捷键。语言惯例术语、缩写与代词术语Terminology术语一致全篇使用同一术语例如统一用 LLM而不是一会儿 LLM 一会儿 AI model产品名正确大写VS Code、JetBrains、Continue功能名大小写一致Chat、Edit、Agent、Autocomplete 等 Continue 功能名统一使用首字母大写。缩写Abbreviations首次出现时拼写全称之后统一使用缩写常见缩写LLMLarge Language Model、IDE、API、URL。例如在文档中首次提到 LLM 时应写明 Large Language Model (LLM)之后才能直接使用 LLM。代词Pronouns用 you 直接称呼用户用 it 指代工具/模型除非指 Continue 团队本身否则避免使用 we。配套规则description 与 Mintlify 格式Style Guide 并不是孤立的一份文件仓库中还有两份与其直接配套的文档规则description 字段强制要求documentation-description-rule.md 要求docs/下每个文件的 frontmatter 都必须包含description字段用于概括页面内容长度 100-160 字符要求精炼、包含关键词、说明用户能从该页学到什么或完成什么。其目的是帮助用户和搜索引擎在阅读前理解每页内容SEO 优化与可发现性。例如 docs/autocomplete/how-to-use-it.mdx 的 description 就是一段 100 字符、关键词丰富、说明学习成果的句子。Mintlify 组件格式规范mintlify-formatting.md 则规定了Card、Info、Tip、Note、Warning、CardGroup、Frame等 Mintlify 组件的排版要求组件开标签之后、闭标签之前必须留空行组件内容缩进 2 个空格列表项逐行书写有序/无序列表各自独立成行链接在列表中的写法- Link Text: Description of the link嵌套组件如CardGroup内嵌Card要保持层级缩进一致。正面示例正确写法Info Important information here: - Point one - Point two - Point three /Info反面示例错误写法Card titleExample iconicon-name This is wrong: - All bullets - On one line - Bad formatting /Card该文件还特别强调当使用 Continue 或其他 AI 助手生成或修改文档时必须按照这些规则格式化 Mintlify 组件——这正是这套规则要解决的核心工程问题让 AI 产出的文档格式与人工维护的文档保持一致。从源码看文档规则如何落地文档与配置的联动Continue 的文档写作不是空对空的文案工作Style Guide 中配置示例要用代码块并带语法高亮的要求与真实配置体系严格对应。Continue 的配置采用 YAML 格式存储在~/.continue/config.yamlMacOS/Linux或%USERPROFILE%\.continue\config.yamlWindows文档中的配置示例直接来自这套 schema。在源码层面配置的解析与校验分布在 core/config/ 目录其中 ConfigHandler.ts 负责加载与热更新配置validation.ts 负责校验配置合法性types.ts 定义了完整的配置类型体系模型、规则、提示词、上下文提供器等。文档写作者在编写配置示例时需要以这些真实 schema 为准确保示例可复制、可运行。规则文件如何被产品使用从实现层面看Rules 的加载与匹配逻辑位于 core/config/loadLocalAssistants.ts 和 core/config/workspace/ 等相关模块中。规则文件通过 globs 模式与文件路径匹配命中后即作为系统上下文注入到 Chat、Edit、Agent 会话中参见 docs/customize/rules.mdx 中 Your agent detects rules and applies the specified rules while in Agent, Chat, and Edit modes 的说明。因此documentation-standards.md中的globs: docs/**/*.{md,mdx}就是告诉 Agent当你在处理docs/下的 Markdown/MDX 文件时请遵循这份文档风格。如何检查自己的文档是否符合规范仓库中的docs/目录本身就是一个活生生的答案集。写作时可以对照以下清单自查基调是否使用第二人称 you、祈使句、主动语态是否避免了被动语态与空洞的官腔表达结构是否按视觉引入 → 目的陈述 → 分步操作 → 平台差异 → 进阶技巧组织标题是否从##开始、采用动词 宾语格式frontmatter是否包含title、description100-160 字符、keywords快捷键是否统一为cmd/ctrl X格式并覆盖 Mac/Windows/Linux交叉引用是否使用描述性锚文本 相对链接平台覆盖VS Code 与 JetBrains 是否都覆盖且 VS Code 优先Mintlify 组件开闭标签之间是否留空行、内容是否缩进 2 空格、列表是否逐行书写总结与最佳实践Continue 的 documentation-standards.md 是一份可执行、可自动加载的文档风格规则它把好的技术文档拆解成了可检查、可复用的具体条款写作基调上对话式、直接、帮助导向用 you 称呼用户、用 it 指代工具指令用祈使句内容结构上五段式页面组织 动作导向标题 平行列表技术规范上统一快捷键写法、代码块高亮、描述性相对链接、双平台覆盖语言惯例上术语与功能名大小写一致、缩写首次全称、避免使用 we配套机制上与description强制规则、Mintlify 组件格式规则协同形成完整的文档工程约束。对任何正在做开发者工具、IDE 插件或 AI Agent 项目的团队这套规范都值得直接借鉴把文档风格写成一个 Rule 文件放进.continue/rules你的 AI 编码助手在写文档时就会自动遵循同样的标准从而让 AI 生成内容与团队手工维护内容在风格上无缝对齐——这正是 Continue 用自家产品实践文档工程化的缩影。【免费下载链接】continueopen-source coding agent项目地址: https://gitcode.com/GitHub_Trending/co/continue创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表