关于文档编写的几个思维
近期重新组织了好几篇技术文档,把其中的一些感悟提炼出来。
文档为达到容易理解和操作的程度,对大量的语言重新组织,内容的不同呈现,借助辅助工具等一系列操作,本文就是剖析整个流程
全文主要的流程是:
程序员一定会是接触各种各样的技术文档,文档写的好与不好,大致都能区分出来。
但是对于自己写的文档却可以容忍 “丑陋” 、“难以理解”等......
对技术、代码可以修改、修改、再修改,优化、优化、再优化......
我觉得出现问题在于:程序员对于如何有效的逻辑表达以及优秀的排版没有意识。
据我观察,一个程序员完成了一份代码的编写,对文档只会花小部分时间进行书写,会自然而然的忽略部分信息,认为把信息堆砌出去,就是一篇文档......
不不不,我认为不应该这样......
但凡伟大的公司、产品对“呈现” 这一块都绝对的重视。尽量都在简化用户的操作复杂程度,比如极度克制的微信。
如何定义一份文档是通俗意义上的好?
就个人的认识,可以从 GitHub 上的最热门的开源项目的文档入手?
比如个人最崇拜的世界 Python 技术排名第五的作者: kennethreitz,他的开源作品:requests
再比如:开源 web 框架 Django
这两个项目的文档堪称是教科书式文档示例。
阅读这些项目的文档,一定有个感官的认识:文档写的好,根据文档能使用起来,整体文档的风格也高度的统一。
一个好的文档我认为具有下面三个特点:准确、清晰和美观
准确和清晰对应逻辑梳理和表达。 美观对应排版。
pic_1.png
我现在的步骤是:
梳理环节主要是关注现有文档的整体流程以及你如何可以对现有流程优化
实践环节主要是关注那些 ‘坑’,直到你成功的按照步骤得到理想的结果
现在手头你已经有历史经验(收集的资料)和 实践经验(实践环节)。
进行文档的编写需要注意两个点:
一篇文档主要包含这些内容:
pic_2.png
这里有一篇中文技术文档写作规范参考:阮一峰:中文技术文档写作规范
标题:
我只谈论一点:标题原则上存在六级,即一级、二级、三级、四级、五级和六级标题。但我推荐使用前三级标题,其余的使用列表项目进行组织。因为层级组织多了,其实是并不太友好。
文本:
参考示例中讲了很多,我值谈论三点:
段落:
我谈论一点:
图片:
我谈论两点:
表格:
我谈论一点:
其他:注意整体风格。
综上:编写文档的两个思维是:
pic_3.png