Skip to main content

如何写好文档

为了持续改善文档质量，特编写相关指引，通过简单易懂的规则，让每个参与钉钉开发者百科的开发者都可以持续输出高质量文档。

术语规范​

专业术语，需要保持其大小写正确性：

  • DingTalk：钉钉。避免使用 dingTalk、Dingtalk、Dingding

常用英文单词，或者总所周知的术语，按照一个单词来使用，避免拆成两个单词：

  • Timestamp，而不是 timeStamp、time-stamp
  • Callback，而不是 callBack、call_back
  • Input，而不是 InPut、inPut
  • Output，而不是 OutPut、outPut
  • Endpoint，而不是 EndPoint、endPoint

有特定大小写规则的术语，不要混淆代码规范和文档规范

  • OpenAPI，在文档中不要写成了 openApi、OpenApi、OAPI
  • App ID
    • 在文档中，一律使用“App ID”，两个单词中间有空格。不是 appId、AppID、AppId、Appid、appid
    • 在代码中，遵守相应编程语言的规范，例如 Java 代码中的 appId 和 Python 代码中的 app_id 都是推荐的用法
  • User ID，同上，在文档中不要写成 userId、UserID
  • Corp ID，同上，在文档中不要写成 corpId、CorpID

特定产品/功能术语

  • Private Chat：IM 中的单聊在钉钉中翻译为 Private Chat，不要用 Single Chat

排版规范​

  • 中英文之间要有空格
    • 正确：钉钉 OpenAPI 使用规范
    • 错误：钉钉OpenAPI使用规范
  • 中文和数字之间要有空格
    • 正确：已开放超过 3000 个接口
    • 错误：已开放超过3000个接口
  • 数字和单位之间不需要空格
    • 正确：10MB
    • 错误：10 MB
  • 全角标点和其他字符之间不加空格
    • 正确：已经成功接入钉钉 OpenAPI，开始业务功能集成
    • 错误：已经成功接入钉钉 OpenAPI ，开始业务功能集成

命名规范​

URL 命名​

文档的 URL 命名采用英文小写字母、字母、中划线组成。

例如：

  • ✅ 推荐使用：/docs/develop/best-practices/permission-deny
  • ❌ 避免使用：/docs/develop/best_practices/permission_deny（下划线）
  • ❌ 避免使用：/docs/develop/bestPractices/permissionDeny（大小写字母）

相关链接​