目录

前言

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

对公司而言

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

标准化流程

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

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

如何实现 SOP?

• 由外部引入

  • 好处: 有参考案例
  • 坏处: 兼容度不确定

• 从内部总结

  • 好处: 契合自身实际
  • 坏处: 需要长时间的积累

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

最佳实践

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

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

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

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

对自己而言

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

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

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

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

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

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

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

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