内容指南

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

重要

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

文档组织结构

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

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

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

注解

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

重要

在删除或移动 .rst 文件时,请根据你所在分支的版本(例如:17.0.txt)更新 redirects 文件夹中相应的文本文件。为此,请在相关部分的底部(例如:# applications/sales)添加新的一行。在这一行中,首先添加旧文件位置的重定向入口点,后跟一个空格,然后添加新文件位置或相关文件位置的出口点。例如,如果将文件 unsplash.rstapplications/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 SalesSales 应用程序等。

  • 按照 Odoo 中的显示方式大写标签(例如字段和按钮)。如果标签全部为大写,则将其转换为句子大小写。

  • 如果冒号后是一个完整的句子,则将首字母大写。

  • 避免大写普通名词,例如 “sales order” 和 “bill of materials”,除非引用标签或模型。

语法时态

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

Example

良好示例(现在):
截图会自动调整大小以适应内容块的宽度。
错误示例(未来):
当你截取屏幕截图时,请记住它会自动调整大小以适应内容块的宽度。

列表

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

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

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

小技巧

  • 使用内联文本来进行解释,或者当列表项不超过三个时使用。

  • 在适当的地方使用 嵌套列表 来结合项目符号列表和编号列表。

  • 考虑将简单的步骤分组在同一个列表项中,例如:转到 网站 ‣ 站点 ‣ 页面 并点击 新建

  • 仅当列表项构成完整句子时,才在末尾使用句号。

Example

项目符号列表

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

  • 产品: 需要补货的产品

  • 位置: 产品存储的具体位置

  • 仓库: 产品存储的仓库

  • 在手数量: 当前可用的产品数量

编号列表

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

    • 要么打开 Website 应用,点击右上角的 + 新建,然后选择 页面

    • 或者前往 网站 ‣ 站点 ‣ 页面 并点击 新建

  1. 输入一个 页面标题;该标题将用于菜单和页面的 URL。

  2. 点击 创建

  3. 使用网站构建器自定义页面的内容和外观,然后点击 保存

图标

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

Example

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

图像

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

重要

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

屏幕截图

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

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

  1. 调整 浏览器的宽度,可以通过 调整窗口大小 或打开 浏览器的开发者工具 并调整宽度来实现。

  2. 选择 相关区域,而不是保留整个窗口。

  3. 删除 不必要的信息,并在适用时 调整 列的大小。

重要

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

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 标签应为 在设置应用中激活开发者模式

在设置应用中激活开发者模式