文档标准
文件组织
- 文件名除
index.md
外,均应写成首字母大写单词+下划线空格的模式;- 如:
code style.md
应改写成Code_Style.md
- 如:
文档内容
- 文字描述请说人话;
- 命令至少应当有解释、用法和示例;
- 解释:描述命令的作用;
- 用法:描述使用命令的方法;
- 示例:体现命令用法的完整代码;
- 在命令的用法部分,使用
TODO
标准; - 对于有可预见错误的脚本,应注明;
- 对于含报错信息的文本,应注明;
- 合理运用表格、列表说明并列的事务;
格式规范
- 对于专有名词应加粗;
- 外链禁止使用超链接,而是直接使用外链的地址。
- 对于含外链的文本应使用引用格式;
- 禁止外链(连接到官方文档的除外);
- 英文与中文之间应手动打上空格,英文与中文标点之间不打空格;
- 如“点击 File 按钮”,“这个 File。”
- 对于文件名、代码短语的引用,需使用
行内块
。 - 出于排版考虑,可善用全角化的半角字符;
- 正文中不加入 toc 目录
- 对脚本、文件或命令行显示等具有“行”的要素的部分,应使用代码格式;
- 克制对 Emoji 的使用;