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，即使指代的是单个人
- 当描述真实人物时，使用该人偏好的代词
- 包容性别认同、种族、文化、宗教、能力、年龄、性取向和社会经济阶层——在示例中包含多种职业、文化、教育环境、地区和经济环境
- 避免政治化内容——在必须包含政治内容的情况下，保持中立
- 不要对人、国家和文化做出任何概括，即使是正面或中性的概括也不行
- 不要撰写针对任何社区（尤其是少数群体）的偏见和歧视性内容
- 避免使用与历史事件相关的定性术语
- 避免使用与暴力和军事行动相关的术语和隐喻
8 个赞
mcwumbly
(Dave McClure)
2
@hugh / @SaraDev
我在这里看到标题有些不一致。
我们有这些例子：
但接着我们又说：
如果我将“正确”的示例输入转换器，我会得到这个：
Enable Automatic Titles for Chat Threads
我们应该更新示例以匹配吗？
aside
如果由我决定，我会认为我们应该采用句子大小写，而且我不确定为什么我们当前的帖子标题中“Chat Threads”是大写的，所以我个人更希望看到这个：
Enable automatic titles for chat threads
但最终一致性更重要，我将假设你们有充分的理由选择当前的建议。
1 个赞
hugh
(Hugh Lashbrooke)
3
这是一个很好的发现——我之前没有想到这一点，但很容易更新。然而：
标题大写规范是我的决定，因为我觉得它通常看起来更简洁、更专业。我认为这很大程度上是我的主观意见，因为 Google 和 Microsoft 都建议在文档标题中使用句首字母大写。我找到的其他网站也建议使用句首字母大写，所以我将撤销此更改并更新那里的大小写要求。
3 个赞
mcwumbly
(Dave McClure)
4
我也注意到他们建议对标题 和 章节名都使用句子首字母大写。（我和您在同一个团队）。
看起来我们目前没有明确我们对章节名的偏好。我们顺便也加上吧。
1 个赞
mcwumbly
(Dave McClure)
6
好的，既然我状态这么好……
我喜欢我们这样说：
但在指南中，我们目前有这个例子：
我的看法是，在这里大写“隐藏网站设置”是不必要的。（诉诸权威）
2 个赞
hugh
(Hugh Lashbrooke)
7
我感谢你的申诉 
是的，这是一个很好的观点——那个例子是从一份真实文件中提取的，我们在其中使用了现有文档的标题来描述它，由于该文档使用了标题大小写，因此引用也使用了标题大小写。随着从标题大小写更改为句子大小写，该引用也应更新。
1 个赞
mcwumbly
(Dave McClure)
8
根据上述对话，我对这份风格指南进行了一些修改。
- 将主题标题更改为句子大小写
- 将标题更改为句子大小写
- 删除了不必要的资本化（Syntax）
- 将标题中的和号 (&) 替换为“and”
- 将标题中的斜杠 (/) 替换为逗号或连词
最后两项更改并未进行讨论——如果它们看起来多余或与指南不符，请告知我（或者，我们是否应在指南中捕获这些指南）。
2 个赞
hugh
(Hugh Lashbrooke)
9
我喜欢最后两个——它们绝对符合指南的精神，并且值得包含在指南本身中。我现在就添加它们。
1 个赞
simon
11
除了避免使用习语外，我一直避免在文档中使用缩略语。我认为这会使非英语/非西方读者更难理解。英语是一种奇怪的语言。
而且？
在某个时候，我们（可能是我）开始使用内联代码来引用站点设置。例如：“启用 discourse connect 站点设置。”这可能是正确的方法，但感觉有点开发人员风格。
也许值得使用一个一致的占位符名称来指代 Discourse 站点。比如 discourse.example.com？这里有一些文档引用 Discourse 站点为 sitename.com。这真的让我很困惑。
一些通用的写作建议：像目标受众的成员一样阅读你写的内容（看看缩略语有多么棘手）。确保你对受众先验知识的假设是合理的。
我很感激不再有大量文档主题归属于我，但将 Discourse 作为 所有 团队文档主题的作者感觉有点冷淡。
让我重新找回写作乐趣的是这个建议：寻找方法将你的一部分融入你所写的任何内容中。可以是任何东西，你的语气、你的爱好，任何东西……这与这里推荐的做法有点相反。
6 个赞
maiki
(maiki)
12
嘿，Simon！ 
我本来想看看会发生什么，但嗯，我和你的看法一样，我尽量避免使用缩略语。
哈哈，是的……我不会在文档中使用这些词，以免暴露我的 
。
绝对是：Example Domains
这就是我想来讨论的重点！ 
我们对此进行了很多来回的讨论，很高兴看到它默认包含在风格指南中。
我认为这很重要，原因如下：编写文档需要尽可能地让我们的社区成员都能访问，包括（尤其是？）我们的 Discourse 团队成员。
Discourse 是一个社交、讨论软件。而有些文档实际上是一个持续的对话。如果我分享关于如何为我的社区成员入职的实践，我希望自己被呈现为该主题的“所有者”，这样我就可以回答问题并扩展该主题。
另一方面，如果客户询问我们从未解释过的功能，我希望能够使用风格指南并编写有用的、通用的文档，我认为成为主题所有者会阻碍发布。
另外，如果我们要在 Discourse 之外编写文档（集成或从代码注释生成等），拥有一个“文档用户”可能更容易作为实现细节。 
我不认为本指南会阻止人们注入他们的声音和个性，并进行讨论。但如果它能帮助更多的人开始文档编写实践，而他们否则不会这样做（然后我们可以鼓励他们变得更具个性！），那就太好了！
3 个赞
hugh
(Hugh Lashbrooke)
13
在有本地化文档的原生处理方式之前，我认为在标题前加上标志是处理它的最实用方法，并且是该指南的一个合理例外。
我认为这类事情有不同的意见和偏好，但对于这个风格指南，我们遵循公认的行业规范。再次强调，Google 和 Microsoft 的指南都同意使用常见的缩写更好。
话虽如此，我确实读过一些帖子建议使用否定缩写（如“can’t”）可能会让非英语母语者更难理解。我们将对此进行更深入的研究，并在必要时相应地更新风格指南。
我已经删除了那个例子！
是的——这很常见（不仅在 Discourse 中），但我同意这并不完全正确。使用引号会更好，所以我认为我会在风格指南中明确这一点。
这是一个很好的观点——我会在风格指南中加入这一点！
感谢您的反馈！@maiki 在上面提出了一些很好的观点，我同意他所说的。我想补充的是，我们已将官方文档切换为由 @Discourse 作为作者的原因之一是，为了让读者，特别是第一次接触文档的读者，感受到更大的权威性。这也是整个风格指南的初衷。
任何撰写文档的人当然仍然可以在他们的写作中注入个性，并且关于单个文档主题的讨论也不会消失，所以这总是一个让事情更具个性化的地方。
非常感谢所有这些反馈 
2 个赞
ondrej
14
关于指南中的元信息块。虽然指南规定文档主题需要一个元信息块，但并非所有主题都有 ，而且它们在这里并不总是保持一致，以下是我找到的一些指南中的示例。
“ 所需用户级别：任何用户”
“ 所需用户级别：所有用户”
“ 所需用户级别：任何用户”
个人而言，我更喜欢“所有用户”。
在收集一些反馈之前，我不想随意更改主题中的内容
4 个赞
所有的 @Discourse 文档都在处理中，希望最终都能统一 (
)。不过关于不一致这一点说得很好。我不确定最终会选择哪一个，但我们一定会确保选定一个并坚持使用。
4 个赞
我还应该补充一点，对于任何你看到包含新信息块的内容，都意味着它们已经通过了“第一阶段”并进入了审查阶段——所以如果你读到某个内容并认为“那不对”或“缺少一些信息”，并且你很慷慨愿意提供一些反馈，请在帖子中添加你的想法。
5 个赞
Moin
17
顶部的必需用户级别信息有什么作用？我以为它会提供有关文档是否与我相关的信息。这样我就可以阅读它并决定“我不是 xxx，所以不相关”。
但似乎它的用途不同，例如，TL3 以下的用户可以编辑维基，所以它也与其他用户相关。
3 个赞
hugh
(Hugh Lashbrooke)
18
感谢您指出这一点，@Moin - 该主题已更新，以纠正所需的用户级别。
您对该信息用途的理解是正确的 - 它应该说明什么用户级别或类型能够执行文档中所述的操作。
1 个赞
