前言

个人札记, 写下对 写文档 这件事情的理解, 欢迎讨论.

对公司而言

文档系统是 标准化流程 和 最佳实践 的温床. 我们不仅是在编写文档, 更是在打造一个属于公司的文档系统.

标准化流程

在大部分企业的发展进程中, 都需要孵化出属于自己的一套 SOP(标准化操作流程), 完善的 SOP 最终会覆盖到企业所有业务流程. 例如: 开发团队业务中的 标准化开发流程, 标准化开发环境, 标准化代码编写, 标准化注释与代码文档生成 等.

为什么需要标准化?
这个问题类似于 为什么需要规范的代码风格? 规范代码风格的实践意义在于让团队的合作更加无缝, 让代码的承接更加流畅. 而 SOP 蕴含了更大的意义, 其能带来诸如: 降低公司规模扩大所带来的阻塞感, 让公司的管理细节更加透明, 由体制和流程来调度员工, 降低对人的依赖 等好处. 总的来说, 就是打造一个中心, 让所有人都围着它转, 这样才能够提高向心力和执行力. 公司的每一位成员都是标准的制定者, 同时也标准的执行者.

如何实现 SOP?

由外部引入
- 好处: 有参考案例
- 坏处: 兼容度不确定
从内部总结
- 好处: 契合自身实际
- 坏处: 需要长时间的积累

显然, 后者所总结出来的 SOP 会更加健壮, 而总结的载体就是文档系统.

最佳实践

最佳实践可以理解为最优的问题解决方案, 是在不断实践的基础上作出的经验性结论.

如何让每一次实践都更具价值?

共享: 让所有人都能收获经验值
集思广益: 问题的抛出应该要像打渔撒网一般, 更广的受面意味着更多的可能, 网聚人的力量.
“实践-总结” 的循环迭代: 这同样需要一个载体去承托实践的思路, 并在此基础上不断打磨, 优化.

所以, 文档系统能够让闪现的灵光得以持久化保存, 而不让它消散在讨论声之中.

对自己而言

培养自身表达能力和严谨逻辑思维的方法论.

写文档和写代码本质上是一样的, 都是语言的组织和思想的传递行为. 有科学数据表明, 善于写文档的程序员所写的代码会更加优雅. 因为 结构层次是否分明? 措辞选词是否精准? 科学逻辑是否严谨? 概念定义是否高度抽象? 这些优秀论文的标准, 也同样是优秀代码的标准.

在我们写代码的大多数时间里, 其实都是潜在意识在控制自己, 而我们的主观主观意识. 例如:

使用 print 语句还是 print() 函数?
使用 not in 还是 in ?
使用 for-else 还是 for-跳出缩进 ?
使用 if in 还是 if not in ?

当在使用上述两者都能够实现相同结果的情况下, 你会如何选择? 很可能是由潜在意识, 也就是我们的个人习惯来决定的. 但对于经验丰富的程序员而言, 在选择的时候就可能会考虑到 Python2 和 Python3 的兼容性的问题, 可读性的问题, Pythonic 的问题, 逻辑性完整的问题. 所以:

潜在意识 > 主观意识 ==> 菜鸟
主观意识 > 潜在意识 ==> 老炮

写文档相比于写代码更能培养上述的技术素养, 因为前者不会受到字符串的视觉扰乱和英文语境的阻碍, 更能专注于 思路的完善和扩展.

所以, 当你认为自身的表达能力有所欠缺时, 开始写点东西吧.

如何理解写文档这件事情 ?相关推荐

为什么程序员都不写文档？
‍‍‍ ‍ [CSDN 编者按]对于程序员来说文档可能是他最大的软肋.一些被称之为高手的程序员,往往是文档方面的处理会偏弱.不管这个程序员是在大公司.还在小公司.不管程序是写文档的.还是不写文档的,大 ...
从程序员到项目经理（二十九）：怎样写文档
在软件项目中,文档既是一项的重要成果,也是项目管理的有力工具.通过文档,可以稳定.明确的传达信息,实现项目内的有效沟通.所以写文档对项目经理来说,是一项必备的技能. 然而很多项目经理害怕写文档,似乎 ...
程序员写文档的重要性
写文档的重要性对于软件相关行业,在学校或单位大家也许都已经注意到了,除了要编写的程序.绘制设计图之外,还有一个重要的工作便是写文档.为什么要写文档呢?因为我们要把自己做的东西展示出来,不光展示给同行 ...
程序员都讨厌写文档？这4个工具让你事半功倍
长按识别上方二维码,关注公众号:后端面试那些事回复"报告",获取你的GitHub年度报告! 对于一般的程序员来说,花费数小时来创建代码或修改现有代码只是一天工作中的一部分,简而言 ...
java开发文档怎么写_程序员该不该写技术文档，怎么写文档，易懂又能提升自己...
最近公司项目的调用量突然涨了一大波,很多系统都纷纷扛不住了,于是需要对系统进行优化,系统优化的第一步,便是梳理业务! 在这个过程中,经常出现了这样一些情况,发现数据库的某些字段,没有注释,也没有一定的 ...
flowable 中文文档_滴滴实习收获 | 产品经理就是写文档和开会沟通的吗？
本篇文章希望和大家分享我今年的2个思考:一是为什么需要产品经理,二是产品经理的工作核心逻辑是什么.内容会结合<俞军产品方法论>和我自己在滴滴国际化做产品实习的经历. 一.为什么需要产品经理 ...
比Word更优雅的记笔记/写文档/交报告方式
比Word更优雅的记笔记/写文档/交报告方式 markdown+vscode->pdf 背景最近在上的一门<信息系统开发工具>课老师要求实验以后都要交实验报告,但是和以往不同的是, ...
不给代码写文档，让代码文档化
这是程序员讨论了很久的一个话题:要不要给代码写文档?值得给代码写文档吗? 我曾经觉得这个话题实在是让人难以应付.也认为除去一些特殊的情况(比如编写公用 API),代码文档并不是那么必要.直到有一天,我 ...
跟着吉庆写文档（流程图）の让“伊妹儿“帮你管理时间
第一版: 由于第一次写文档,只是知道工作所强调的主要内容,但是不知道应该以什么样的形式来表达而已.因此,只是写了一个大概的框架. 吉庆学长: 1)时间管理实际上就是个人管理 2)加载一些图片--图文并 ...

如何理解写文档这件事情 ?

目录

前言

对公司而言

标准化流程

最佳实践

对自己而言

如何理解写文档这件事情 ?相关推荐

最新文章

热门文章