Discourse 文档目前正在审查和编辑中，以与本风格指南保持一致。并非所有文档主题目前都与本指南完全匹配——我们正在尽快实现这一目标。
本文档被视为一份动态文档，用于指导 Discourse 文档 的撰写和格式规范。如有需要，本主题将随时更新。如果您对本指南中的任何原则有疑问，请在本主题中发帖讨论具体细节。
本文档风格指南的核心理念是：在撰写文档时，要始终考虑读者及其需求——他们希望完成什么任务？您提供这些内容的目标是什么？
实施本风格指南时的快速检查清单：
- 元信息块已存在且正确
- 标题具有行动导向性
- 所有标题均采用句子大小写
- 使用了正确的标签和分类
- 文档结构逻辑清晰
在完成文档时，请检查是否满足以上所有标准。
请注意以下文本格式指南：
元信息
- 文档应归属于以下类别中的且仅一个：
- 使用 Discourse
- 面向非管理员任务的一般用户指南
- 站点管理
- 设置、插件、内容及一般站点管理
- 集成
- 将其他平台与 Discourse 集成的指南
- 托管客户
- 仅对托管客户相关的指南
- 自托管
- 仅对自托管站点相关的指南
- 开发者指南
- 在 Discourse 之上进行开发的技術指南，包括创建主题、主题组件和插件
- 贡献
- 为 Discourse 开源项目做出贡献的指南
- 使用 Discourse
- 文档应归属于以下标签/文档类型中的且仅一个：
#how-to#explanation#reference#tutorial
- 文档可包含其他适用标签，但单个文档的标签总数绝对不得超过 5 个
元信息块
所有文档必须在顶部包含一个信息块，简要说明文档内容，以及任何相关的元信息，例如用户级别要求、是否需要控制台访问权限等。该信息块将格式化为引用块，上方不带标题。以下是示例：
本指南旨在描述所有可用的隐藏站点设置，如何启用它们，以及为何您可能需要调整它们。
所需用户级别：管理员
需要控制台访问权限
标题和副标题
- 使文档标题具有行动导向性
- 错误：“如何为聊天线程启用自动标题”
- 正确：“为聊天线程启用自动标题”
- 文档标题不应过长
- 对于“操作指南”类主题，标题应侧重于目标
- 所有标题必须具体且唯一
- 除逗号外，文档标题中不要使用标点符号或特殊字符
- 文档标题中不要包含表情符号
- 标题和副标题使用句子大小写——即只有第一个单词首字母大写，专有名词以及通常大写的其他单词除外
- 标题中不要使用符号（&），而应使用完整单词（“和”）
通用写作指南、语气和语法
- 在指代阅读文档的人员时，使用第二人称 语气——即使用“你”，而不是“我们”
- 尽可能使用主动语态
- 错误：“应点击该按钮”
- 正确：“点击该按钮”
- 首次使用缩写词或缩略语时进行定义，必要时可提供外部链接以提供更多信息
- 使用简短句子，并通过较短的段落、标题和列表来分割文本
- 可使用
**粗体**和*斜体*来强调关键短语或单词，但不要过度使用 - 避免在未解释的情况下使用行话或技术术语——如有疑问，宁可多解释
- 在描述视觉界面（如 UI 元素）时，使用截图
- 除非明确允许，否则不要记录或试图披露 Discourse 未来的功能、产品或服务
- 使用过渡词，例如 因此、虽然 和 此外。
- 使用常见缩写：it’s, you’ll, you’re, we’re, let’s
- 在文档中体现永恒性——避免使用 soon（即将）、new（新）、now（现在）、latest（最新）等很快就会过时的词汇
- 不要赋予软件或硬件人类特质
- 例如：“如果你向此 API 传递一个整数，它会生气并抛出错误”
- 例如：“我们友好且雄心勃勃的 AI 机器人将帮助你解决所有问题”
- 引用文本（包括来自 Discourse UI 的文本）时，使用“引号”
- 引用 URL 时，使用
反引号 - 使用示例域名时，使用
discourse.example.com - 如果有用，可以在段落开头使用表情符号来突出显示。单个主题中不要使用超过两到三个表情符号。一些可用的示例表情符号：
- - 信息性注释
- 公告或通知
- 警告信息
- 非常重要的信息
- 避免：
- 不必要的隐喻或幽默
- 文化和地域 references
- 以居高临下的语气规定或命令操作步骤——例如 你必须点击 发布 或 你需要点击 发布
- 过于礼貌。例如，请点击 发布
- 除非绝对必要，否则不要使用感叹号
- 在不必要的地方大写单词
- 过度重复使用相同的短语和代词
面向最终用户的文档：
保持友好、非正式的语气，重点是以专业的方式做到清晰简洁。迅速切入主题。解释技术术语，但注意不要显得居高临下。为确保清晰，首先简要说明当前主题的上下文。
面向开发者和技术的文档：
保持直接、精确的语气。使用与用户文档相同的语气，但可以假设读者具备更高水平的技术知识。
结构
- 迅速切入主题——首先呈现最重要的内容
- 在文档早期包含重要关键词
- 让读者的选择和后续步骤显而易见
- 始终使用轻量级标记语言编写文档（Discourse 已内置 Markdown-it）。
- 以逻辑流程组织文档——从概述开始，接着是详细章节，如有适用则提供总结或结论
- 使用标题和副标题来组织内容，使读者更容易浏览并找到特定信息——使用标题的层级结构，从 h2 开始，不要跳过层级
- 在文档中提供指向相关主题或章节的链接——这有助于用户无需不必要的搜索即可找到额外信息
链接
- 链接文本应具有意义
- 除非 URL 格式本身重要或具有指导意义，否则不要将 URL 用作链接文本——而应使用页面标题或页面描述
- 链接到外部网站和来源，而不是引用或重写现有文档
- 确保所链接的网站具有高标准和高质量
- 如果链接会下载文件，请明确说明——同时注明下载的文件类型和大致文件大小
文档中的代码
- 对于大型代码示例，尽可能使用带语言特定语法高亮的代码块
- 如果代码示例本身不清晰，请用引导性句子介绍该示例——如有疑问，宁可多解释
- 代码示例应遵循相关编程语言的最佳实践
- 对于表达基本代码属性或无需完整代码块的情况，使用行内代码，例如：
- 属性名称和值
- 类名
- 命令行工具名称
- 数据类型
- 环境变量名
- 文件名、文件扩展名和路径
- 文件夹和目录
- HTTP 动词、状态码和内容类型值
- 查询参数名称和值
- 文本输入
- 在代码示例、命令或其他文本中使用 占位符 时，请提供解释说明该占位符代表的内容
- 首次使用该占位符时写出解释；如果在该占位符首次使用后还有多个占位符或步骤，可以再次解释该占位符
- 为用户提供一种简便的方式来复制和运行代码。
- 显示预期输出，可以在代码示例后的单独部分中显示，也可以在代码示例中使用代码注释显示
- 编写安全代码——切勿在代码中硬编码密码、API 密钥或敏感信息
操作步骤和分步指南
- 以一致的方式格式化操作步骤，以便读者通过浏览轻松找到
- 每个步骤使用独立的编号条目
- 包含完成步骤的操作，例如“确定”或“应用”按钮
- 如果说明出现在操作发生的同一 UI 中，通常无需提供位置详情
- 如果需要确保读者从正确的位置开始，请在步骤开头提供简短说明
可访问性和包容性
- 在能增加价值时使用截图、图表或视频，特别是在解释复杂步骤或展示界面部分时
- 图像应用于补充文本信息，而非替代文本
- 始终为图像使用
alt属性 - 始终为视频提供字幕或转录文本
- 仅当你能在文本中完全解释 GIF 内容时才使用 GIF
- 选择简单的图像，裁剪多余细节
- 使用通俗易懂的语言，避免可能无法被普遍理解的比喻或习语
- 考虑到文档将在多种设备上使用
- 使用性别中立的语言。在指代人时，不要使用 他、他的、她、她的 等代词——可以通过以下方式避免使用代词：
- 改用第二人称（你）重写
- 将句子改为复数名词和代词
- 使用 人 或 个体 等词
- 使用冠词 the, an, 或 a 代替代词
- 使用复数代词，如 they, their, 或 them，即使指代的是单个人
- 当描述真实人物时，使用该人偏好的代词
- 包容性别认同、种族、文化、宗教、能力、年龄、性取向和社会经济阶层——在示例中包含多种职业、文化、教育环境、地区和经济环境
- 避免政治化内容——在必须包含政治内容的情况下，保持中立
- 不要对人、国家和文化做出任何概括，即使是正面或中性的概括也不行
- 不要撰写针对任何社区（尤其是少数群体）的偏见和歧视性内容
- 避免使用与历史事件相关的定性术语
- 避免使用与暴力和军事行动相关的术语和隐喻
。
)。不过关于不一致这一点说得很好。我不确定最终会选择哪一个，但我们一定会确保选定一个并坚持使用。