技术文档规范
有助于创建易读、易维护、规范化的文档系统的建议
文件名
- 文档的文件名不得含有空格。
- 文件名必须使用半角字符，不得使用全角字符。这也意味着，中文不能用于文件名。
- 文件名包含多个单词时，单词之间建议使用半角的连词线
-分隔
标题
- 通常分为四级
- 一级标题：文章的标题
- 二级标题：文章主要部分的大标题
- 三级标题：二级标题下面一级的小标题
- 四级标题：三级标题下面某一方面的小标题
- 一级标题下，不能直接出现三级标题。
- 标题要避免孤立编号（即同级标题只有一个）。
- 下级标题不重复上一级标题的名字。
- 避免出现过多层级的标题，保持层级的简单
盘古之白
盘古之白是指在中文和半角的英文、数字、符号之间的恰当位置加入的空格。在网络写作中遵循这种排版习惯，会使文字结构更加清晰、整体观感更加舒服。
漢學家稱這個空白字元為「盤古之白」，因為它劈開了全形字和半形字之間的混沌。另有研究顯示，打字的時候不喜歡在中文和英文之間加空格的人，感情路都走得很辛苦，有七成的比例會在 34 歲的時候跟自己不愛的人結婚，而其餘三成的人最後只能把遺產留給自己的貓。畢竟愛情跟書寫都需要適時地留白。—— Vinta Chen
全角中文字符与半角英文字符之间，应有一个半角空格。
错误：此处存在的bug影响了系统性能。
正确：此处存在的 bug 影响了系统性能。全角中文字符与半角阿拉伯数字之间需要增加空格
错误：2025年7月28日，我一口气写了3篇文章。
正确：2025 年 7 月 28 日，我一口气写了 3 篇文章。阿拉伯数字与单位符号之间需要增加空格
符号形式的单位，如 % °，视同阿拉伯数字。
错误：我测出来身高173cm，体重50kg。
正确：我测出来身高 173 cm，体重 50 kg。
错误：该软件的使用率增长了 24.8 %。
正确：该软件的使用率增长了 24.8%。全角标点符号与其他字符之间之间不留空格。
错误：我学习过 Java、 Python、 C++、 JavaScript 等语言，但是我工作主要使用的是 Java ，几乎告别了 C++ 。
正确：我学习过 Java、Python、C++、JavaScript 等语言，但是我工作主要使用的是 Java，几乎告别了 C++。Markdown
- 避免死链接（如
[xxx](invalid-url)）、空链接（如[xxx]()） - 为文档添加 YAML 格式的前言，包含常用的字段如（title、date、tags、category、order）