内容指南¶
虽然我们鼓励您采用自己的写作风格,但仍需遵循一些规则,以保持清晰度并确保读者能够轻松理解内容。
重要
我们强烈建议在贡献之前阅读 RST 指南与速查表 和主要的 文档 页面。
文档组织结构¶
在撰写关于某个主题的文档时,请保持同一文件夹中的页面井井有条。
对于大多数主题,单个页面即可胜任。将其放置在文档的适当部分(例如,与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
拼写¶
在整个文档中使用美式英语的拼写和语法。
一致性¶
一致性是万物的关键。
确保写作风格保持 一致。在修改现有内容时,尽量匹配现有的语气和呈现方式,或者重写以符合您自己的风格。
大写规则¶
在 标题 中使用句子大小写。
将应用程序名称首字母大写,例如 Odoo Sales、Sales 应用程序等。
按照 Odoo 中的显示方式大写标签(例如字段和按钮)。如果标签全部为大写,则将其转换为句子大小写。
如果冒号后是一个完整的句子,则将首字母大写。
避免大写普通名词,例如 “sales order” 和 “bill of materials”,除非引用标签或模型。
语法时态¶
在英语中,描述和说明通常需要使用 现在时,而 将来时 仅适用于特定事件将在之后发生的情况。
Example
列表¶
列表有助于以清晰简洁的方式组织信息,并提高可读性。它们用于突出重要细节,系统地引导读者完成步骤等。
当顺序重要时,使用编号列表,例如,必须按特定顺序执行的说明、程序或步骤。
当项目的顺序无关紧要时,使用项目符号列表,例如,功能、字段、选项等的列表。
小技巧
使用内联文本来进行解释,或者当列表项不超过三个时使用。
在适当的地方使用 嵌套列表 来结合项目符号列表和编号列表。
考虑将简单的步骤分组在同一个列表项中,例如:转到 新建。
并点击仅当列表项构成完整句子时,才在末尾使用句号。
Example
项目符号列表
以下字段在 补货 报告中可用:
产品: 需要补货的产品
位置: 产品存储的具体位置
仓库: 产品存储的仓库
在手数量: 当前可用的产品数量
编号列表
要创建一个新的网站页面,请按照以下步骤操作:
要么打开 Website 应用,点击右上角的 + 新建,然后选择 页面;
或者前往 新建。
并点击
输入一个 页面标题;该标题将用于菜单和页面的 URL。
点击 创建。
使用网站构建器自定义页面的内容和外观,然后点击 保存。
另请参阅
图标¶
在说明中使用 图标 以帮助读者识别用户界面元素,并减少冗长解释的需要。每个图标都应在括号内附上描述符。
Example
开发者模式激活后,可以通过点击 (bug) 图标来访问开发者工具。
另请参阅
图像¶
添加一些图片来说明文本有助于读者理解和记忆内容。然而,图片不应取代文字:书面说明本身应完整且清晰,不依赖于视觉辅助。应谨慎使用图片,例如,用于强调某个特定点或澄清示例。
重要
不要忘记使用 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
文件夹中。虽然建议不要以这种方式命名 新 图像,但同样重要的是 不要重命名未更改的文件,因为这样做会使仓库中重命名的图像文件体积翻倍。随着引用这些图像的内容更新,它们最终都会被替换掉。