如何让你的文档更规范

引言

“你写的文档啥时候让你爷爷奶奶都看懂，就完事儿了~” —— 来自某乎某topic

当你打开一篇知识文档，映入眼帘的是一张高清的头图，一个有逼格的题目，一句颇有深意的引言，顺着滚动条往下阅读，层次清晰，一字一板。不禁感叹颇具大湿手法。阅毕，随手点赞，称心快意。

文档构造图

上图以系统架构图的方式，呈现文档自下而上的构造图。从最底层的文档核心到最终的文档呈现，就像系统架构中的网络层、存储层到顶层的应用。中间的每一环都密切影响着最终产出的质量。而如何使文档更规范，就需要像插件 Prettier-Code Formatter 做的那样，时刻让编写的代码拥有一致的风格，而其中的过滤器 .eslintrc.json 所做的就是我要讲的主角：规范，也叫规则。

正反案例

案例一

上图案例来自语雀编辑器，左边的文档是经过右边优化来的。

大概使用了的规范：

1. 替换成了更加体现主题的标题。
2. 二级标题 CSRF，专业名词加粗，最好附上链接。
3. 四级标题作为分类介绍的子标题，因为他们都没有下级分类。
4. 素材图最好加上名字。
5. 中英文间保持空格。

这样修改后，整体看上去更加的专业，并且目录结构也变得清晰，通过语雀右侧的大纲，可以更加快速的定位子目录内容。

期刊规范分析

初审

一本书或者稿件在发稿之前，都会经历一步初审，初审的作用就是检查出稿书中字词、语法、知识性等错误，统一书稿的格式，保证排版、文字质量。

初审项目列表：

1. 改正书稿中出现的字词错误、读音错误、知识性错误、语法错误、逻辑错误、欧化错误、观点错误。
2. 统一全书体例，包括统一各级标题、格式、数字用法等。
3. 在书稿上标注需特殊制作的内容，如国际音标、古文字、少数民族文字、外文、插图、表格等。
4. 核查引文、出处和索引；核查参见、互见项目，核查配套内容或项目；核查有关专业知识；核查或核算参考答案。
5. 检查书稿项目，按顺序排次（目录、前言、正文、附录、参考文献、参考答案）。

规范分析

光看初审这几项条目，可想出版书对于规范的重视，毕竟面向广大读者，规范就是对读者最基本的尊重。那么我们程序员在分享自己的文章时，也可以当作是一次出版，让每一篇文档变得更加规范。接下来我们对照着初审的要求来分析一下如何提高文档规范。

1. 文档需要多次审查，避免错别字，特别专业名词，错了就差别大了。
2. 关键推演、实现步骤逻辑要正确。
3. 各级标题合理使用，标题可以生成大纲（目录），语雀提供了四级标题，最外层标题就是二级，一般再没有子目录的标题我会使用四级标题。
4. 中英文、数字间使用空格。
5. 专业词汇（主要英文）加粗，并附上链接。
6. 插图、表格等带上名称并且居中。
7. 斜体一般作着重作用，表示强调；同样使用于正文中夹杂外文句子时使用。van Gogh’s Sunflowers（凡·高的绘画《向日葵》）。
8. 技术文档专有的代码段请使用语雀代码块功能以及行内代码 console.log(hello world)。或者 carbon&t=seti&wt=none&l=auto&ds=true&dsyoff=20px&dsblur=68px&wc=true&wa=true&pv=48px&ph=32px&ln=false&fm=Hack&fs=14px&lh=133%25&si=false&es=2x&wm=false)。
9. 标题与标题间间隔一行；标题与正文间可不加隔行；正文与正文间视情况，隔一行文章显得不拥挤。
10. 引用、素材有出处请附上源出处。同样你自己的文章也标注一下版权信息。语雀提供了水印功能。

文档美感

美感来自于视觉效果，认为富有多样元素、规范统一的排版布局更具美感。直接上图：

案例二（语雀是什么）

总结

除了可供参考的字字条条外，还需要我们不断的优化自己的文档，在一次次的修改中，能逐渐养成自己的写作习惯，最后发现脱离参考也能有不错的排版。多阅读一些大牛的专栏，大牛都是写过无数分享的人，文档格式规范并带有自己的风格。找到喜欢的模仿，也有助于提升我们文档的质量。

参考

优秀文档

• 官方文档最为致命

• 人人都知道反馈，你知道前馈吗？

  规范借鉴

• 稿件格式模板