内容指南¶

虽然我们鼓励您采用自己的写作风格，但仍需遵循一些规则，以保持清晰度并确保读者能够轻松理解内容。

重要

我们强烈建议在贡献之前阅读 RST 指南与速查表和主要的文档页面。

文档组织结构¶

在撰写关于某个主题的文档时，请保持同一文件夹中的页面井井有条。

对于大多数主题，单个页面即可胜任。将其放置在文档的适当部分（例如，与CRM应用相关的内容应放在用户文档 ‣ 销售 ‣ CRM 下），并遵循文档结构指南。

对于更复杂的主题，可能需要多个页面来涵盖其所有方面。通常，您会发现自己正在为一个已经部分涵盖的主题添加文档。在这种情况下，要么创建一个新页面并将其放置在与相关页面相同的层级上，要么在现有页面中添加新部分。当从头开始记录一个复杂主题时，将内容组织在多个子页面中，并在该目录的父页面（即 TOC 页面）上引用这些子页面；尽可能在父页面上编写内容，而不仅仅是在子页面上。通过使用 show-content 元数据指令，使父页面可从导航菜单中访问。

注解

尽可能避免内容重复；如果某个主题已在其他页面中记录，请引用现有信息，而不是重复它。

重要

在删除或移动 .rst 文件时，请根据你所在分支的版本（例如：17.0.txt）更新 redirects 文件夹中相应的文本文件。为此，请在相关部分的底部（例如：# applications/sales）添加新的一行。在这一行中，首先添加旧文件位置的重定向入口点，后跟一个空格，然后添加新文件位置或相关文件位置的出口点。例如，如果将文件 unsplash.rst 从 applications/websites/website/configuration 移动到 applications/general/integrations，请在 # applications/websites 部分下添加以下条目：

applications/websites/website/configuration/unsplash.rst applications/general/integrations/unsplash.rst

文档结构¶

使用不同的 标题级别 来按章节和子章节组织文本。标题不仅显示在文档中，还显示在导航菜单（仅限 H1）和“本页内容”侧边栏（所有 H2 到 H6）中。

H1: 页面标题 The page title gives readers a quick and clear understanding of what the content is about. 本节中的内容从业务角度描述了即将介绍的内容，不应将重点放在 Odoo 上，因为这是文档而非营销材料。在页面标题（H1）下方，以一个引导段落开始，帮助读者确认他们找到了正确的页面，然后在接下来的段落中解释该主题的业务方面。
	H2: 章节标题（配置）第一个 H2 部分是关于功能的配置，或实现特定目标的前提条件。
	H2: 章节标题（主章节）创建与操作或功能数量相同的主章节以进行区分。
		H3: 子章节子章节非常适合评估非常具体的要点。
	H2: 下一节

如何编写好的标题和标题行：

简洁明了：避免使用句子、问题以及以“如何”开头的标题。
不要在标题中使用代词，尤其是第二人称（你/你的）。
使用 句首大写。这意味着你只大写：
- 标题或标题的第一个单词；
- 冒号后的第一个单词；
- 专有名词（品牌、产品和服务名称等）。

注解

大多数标题和标题通常是指一个概念，并且不代表一个功能或模型的名称。
如果缩略词中的单词不包含专有名词，则不要将其大写。
标题中的动词很好，因为它们通常描述一个动作。

另请参阅

写作风格¶

编写文档与编写博客或其他媒介不同。读者更可能通过浏览内容来寻找他们需要的信息。请记住，文档是一个 告知和描述 的地方，而不是说服和推广的地方。

小技巧

尽可能避免使用 you ，在适当的情况下选择使用祈使语气。然而，不要为了避免直接称呼读者而使句子复杂化。

Example

Good example:

从下拉菜单中选择合适的选项。

Bad example:

您可以从下拉菜单中选择合适的选项。

拼写¶

在整个文档中使用美式英语的拼写和语法。

一致性¶

一致性是万物的关键。

确保写作风格保持一致。在修改现有内容时，尽量匹配现有的语气和呈现方式，或者重写以符合您自己的风格。

大写规则¶

在标题中使用句子大小写。
将应用程序名称首字母大写，例如 Odoo Sales、Sales 应用程序等。
按照 Odoo 中的显示方式大写标签（例如字段和按钮）。如果标签全部为大写，则将其转换为句子大小写。
如果冒号后是一个完整的句子，则将首字母大写。
避免大写普通名词，例如 “sales order” 和 “bill of materials”，除非引用标签或模型。

语法时态¶

在英语中，描述和说明通常需要使用 现在时，而 将来时 仅适用于特定事件将在之后发生的情况。

Example

良好示例（现在）：

截图会自动调整大小以适应内容块的宽度。

错误示例（未来）：

当你截取屏幕截图时，请记住它会自动调整大小以适应内容块的宽度。

列表¶

列表有助于以清晰简洁的方式组织信息，并提高可读性。它们用于突出重要细节，系统地引导读者完成步骤等。

当顺序重要时，使用编号列表，例如，必须按特定顺序执行的说明、程序或步骤。

当项目的顺序无关紧要时，使用项目符号列表，例如，功能、字段、选项等的列表。

小技巧

使用内联文本来进行解释，或者当列表项不超过三个时使用。
在适当的地方使用嵌套列表来结合项目符号列表和编号列表。
考虑将简单的步骤分组在同一个列表项中，例如：转到网站 ‣ 站点 ‣ 页面并点击新建。
仅当列表项构成完整句子时，才在末尾使用句号。

Example

项目符号列表

以下字段在补货报告中可用：

产品: 需要补货的产品
位置: 产品存储的具体位置
仓库: 产品存储的仓库
在手数量: 当前可用的产品数量

编号列表

要创建一个新的网站页面，请按照以下步骤操作：

- 要么打开 Website 应用，点击右上角的 + 新建，然后选择页面；
- 或者前往网站 ‣ 站点 ‣ 页面并点击新建。
输入一个页面标题；该标题将用于菜单和页面的 URL。
点击创建。
使用网站构建器自定义页面的内容和外观，然后点击保存。

另请参阅

RST 速查表：列表

图标¶

在说明中使用图标以帮助读者识别用户界面元素，并减少冗长解释的需要。每个图标都应在括号内附上描述符。

Example

开发者模式激活后，可以通过点击 (bug) 图标来访问开发者工具。

另请参阅

RST 速查表：图标

图像¶

添加一些图片来说明文本有助于读者理解和记忆内容。然而，图片不应取代文字：书面说明本身应完整且清晰，不依赖于视觉辅助。应谨慎使用图片，例如，用于强调某个特定点或澄清示例。

重要

不要忘记使用 pngquant 压缩你的 PNG 文件。

屏幕截图¶

截图会自动调整大小以适应内容块的宽度。这意味着如果它们太宽，在低分辨率屏幕上将无法阅读。我们建议除非绝对必要，否则避免使用应用程序的全屏截图，并确保图像的宽度不超过 768-933 像素的范围。

以下是一些改进截图的技巧：

调整浏览器的宽度，可以通过 调整窗口大小 或打开 浏览器的开发者工具 并调整宽度来实现。
选择相关区域，而不是保留整个窗口。
删除不必要的信息，并在适用时调整列的大小。

重要

不要在截图使用矩形或箭头等标记。相反，裁剪图像以突出显示最相关的信息，并确保文本说明清晰且不言自明，不依赖图像。

Example

良好示例（调整了浏览器大小，没有不必要的列，调整了列宽，裁剪了内容）：

错误示例（全宽截图）：

媒体文件¶

一个 媒体文件名：

使用 小写字母 书写；
与媒体的内容相关。（例如，screenshot-tips.gif）；
用 连字符 - 分隔单词（例如，awesome-filename.png）。

每个 RST 文件都有其自己的文件夹用于存储媒体文件。文件夹的名称必须与 RST 文件的名称相同。

例如，文档 doc_filename.rst 引用了两个放置在文件夹 doc_filename 中的图片。

├── section
│   └── doc_filename
│   │   └── screenshot-tips.gif
│   │   └── awesome-filename.png
│   └── doc_filename.rst

注解

之前，图像文件名大多以数字命名（例如：feature01.png），并放置在单一的 media 文件夹中。虽然建议不要以这种方式命名新图像，但同样重要的是 不要重命名未更改的文件，因为这样做会使仓库中重命名的图像文件体积翻倍。随着引用这些图像的内容更新，它们最终都会被替换掉。

ALT 标签¶

ALT 标签 是图像的 文本替代。如果浏览器无法渲染图像，则会显示此文本。它对于视觉障碍用户也很有帮助。最后，它有助于搜索引擎（如 Google）理解图像的内容并正确索引，从而改善 SEO（搜索引擎优化）。

良好的ALT标签应该是：

简短 (最多一行);
不是对前一句或标题的重复；
对图像中发生的动作的 良好描述；
如果大声朗读，很容易理解。

Example

以下截图的适当 ALT 标签应为 在设置应用中激活开发者模式。

另请参阅

RST 速查表：图片

Edit on GitHub