引言
“你写的文档啥时候让你爷爷奶奶都看懂,就完事儿了~” —— 来自某乎某topic
当你打开一篇知识文档,映入眼帘的是一张高清的头图,一个有逼格的题目,一句颇有深意的引言,顺着滚动条往下阅读,层次清晰,一字一板。不禁感叹颇具大湿手法。阅毕,随手点赞,称心快意。
文档构造图
上图以系统架构图的方式,呈现文档自下而上的构造图。从最底层的文档核心到最终的文档呈现,就像系统架构中的网络层、存储层到顶层的应用。中间的每一环都密切影响着最终产出的质量。而如何使文档更规范,就需要像插件 Prettier-Code Formatter 做的那样,时刻让编写的代码拥有一致的风格,而其中的过滤器 .eslintrc.json 所做的就是我要讲的主角:规范,也叫规则。
正反案例
案例一
上图案例来自语雀编辑器,左边的文档是经过右边优化来的。
大概使用了的规范:
- 替换成了更加体现主题的标题。
- 二级标题 CSRF,专业名词加粗,最好附上链接。
- 四级标题作为分类介绍的子标题,因为他们都没有下级分类。
- 素材图最好加上名字。
- 中英文间保持空格。
这样修改后,整体看上去更加的专业,并且目录结构也变得清晰,通过语雀右侧的大纲,可以更加快速的定位子目录内容。
期刊规范分析
初审
一本书或者稿件在发稿之前,都会经历一步初审,初审的作用就是检查出稿书中字词、语法、知识性等错误,统一书稿的格式,保证排版、文字质量。
初审项目列表:
- 改正书稿中出现的字词错误、读音错误、知识性错误、语法错误、逻辑错误、欧化错误、观点错误。
- 统一全书体例,包括统一各级标题、格式、数字用法等。
- 在书稿上标注需特殊制作的内容,如国际音标、古文字、少数民族文字、外文、插图、表格等。
- 核查引文、出处和索引;核查参见、互见项目,核查配套内容或项目;核查有关专业知识;核查或核算参考答案。
- 检查书稿项目,按顺序排次(目录、前言、正文、附录、参考文献、参考答案)。
规范分析
光看初审这几项条目,可想出版书对于规范的重视,毕竟面向广大读者,规范就是对读者最基本的尊重。那么我们程序员在分享自己的文章时,也可以当作是一次出版,让每一篇文档变得更加规范。接下来我们对照着初审的要求来分析一下如何提高文档规范。
- 文档需要多次审查,避免错别字,特别专业名词,错了就差别大了。
- 关键推演、实现步骤逻辑要正确。
- 各级标题合理使用,标题可以生成大纲(目录),语雀提供了四级标题,最外层标题就是二级,一般再没有子目录的标题我会使用四级标题。
- 中英文、数字间使用空格。
- 专业词汇(主要英文)加粗,并附上链接。
- 插图、表格等带上名称并且居中。
- 斜体一般作着重作用,表示强调;同样使用于正文中夹杂外文句子时使用。van Gogh’s Sunflowers(凡·高的绘画《向日葵》)。
- 技术文档专有的代码段请使用语雀代码块功能以及行内代码
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)。 - 标题与标题间间隔一行;标题与正文间可不加隔行;正文与正文间视情况,隔一行文章显得不拥挤。
- 引用、素材有出处请附上源出处。同样你自己的文章也标注一下版权信息。语雀提供了水印功能。
文档美感
美感来自于视觉效果,认为富有多样元素、规范统一的排版布局更具美感。直接上图:
案例二(语雀是什么)
总结
除了可供参考的字字条条外,还需要我们不断的优化自己的文档,在一次次的修改中,能逐渐养成自己的写作习惯,最后发现脱离参考也能有不错的排版。多阅读一些大牛的专栏,大牛都是写过无数分享的人,文档格式规范并带有自己的风格。找到喜欢的模仿,也有助于提升我们文档的质量。