#文档贡献

本文档使用 Rspress 进行编写，文档语法请参考 Rspress 文档，本页用于描述本文档对措辞的要求

#限制性用词参考 RFC 2119

RFC 2119 描述了一些常见用词的意思，简而言之：

#必须、应该

必须要满足的，是强制要求的，通常意味着不如此执行会造成不可预料的后果

#禁止、不应该

必须被禁止的，是绝不允许的，通常意味着如果如此执行会造成不可预料的后果

#建议、推荐、尽量、尽可能

有可能有合理的原因，在特定的场景下可接受，且是被建议的，即能用即用

#不建议、不推荐

有可能有合理的原因，在特定的场景下可接受，但是不被建议的，即非必要不使用

#可以、允许、可选

完完全全是可选的，无所谓有无

#以最新版本为参考

如果在最新版本中，一些行为存在更改，考虑到本应用程序的迭代方式，应该以最新版本为参考。对于不具有向前兼容功能的破坏性修改，应该仅保留最新版本的行为描述（如安装部署方式），但同时，如果已有计划在未来存在破坏性修改，除非是不可预料的，否则应提前在文档中以 danger note 形式警告。反之，如果一些需要向前兼容的功能在最新版本存在破坏性修改，则应该以 warn note 的形式给出警告。

#以客观事实为依据

尚未上线的功能不建议存在于文档中。具体而言：对于尚未承诺的功能，不应该写入文档；对于尚未进行的开发计划不建议写入文档；对于已经开发完毕但尚未上线的功能可以写入文档，但必须做出标注；对于已经上线的功能应该写入文档。

#尽可能全面

对于可能出现的问题和常见错误操作建议写入文档，即文档既应该描述正确做法，也应该描述错误做法。这有助于用户自行排查错误原因。

#尽量避免翻译腔

所谓翻译腔，可以参考中文维基百科中“翻译腔”的条目，简而言之就是“说人话”。但本文档不严格要求翻译腔问题，但最重要的是句子通顺，避免病句。在技术文档中，信达永远比雅更重要。