11｜不只为知识管理：为什么要练习写好文档？
让知识增值
荧光笔
直线
曲线- 深入了解
- 翻译
- 解释
- 总结
《工程师个人发展指南》，新⼈⾸单¥59
全部留言(6)
- 最新
- 精选
6点无痛早起学习的和尚
在工作中我也经常写文档，但是最大的一个卡点就是，文档的更新不及时，就是写完一版技术方案之后，代码、具体实现更新了，就不会把技术方案同步更新了，这就是我最大的一个懒，因为又要花时间去投入其他需求里了作者回复: 你好， 我在想，文档的失步问题，是不是因为你的文档写得太细了呢？还是说，确实技术方案因为软件开发和演进的过程中出现了巨大的变化，从而使得咱必须修订文档。 我建议文档不要太细，而是将概念、关系、接口写清楚即可。文档的作用一定是不应全面取代代码的，不然反而会带来更大的负担甚至因为不及时同步更新而起反作用。 你所面临的这个问题，也是我们向前迈进一步的契机。加油！
2024-05-20归属地：北京7- pyhhou写好一个文档的难度其实并不比编程低。程序是给有技术经验的人看的，至少我们在编程的时候可以假定读代码的人至少有基本的编程经验，还可以假设他们了解一些编程的最佳实践。而文档并不是这样，一个文档不单单是给技术人看的，文档的读者也会是诸如产品经理、项目经理、人力资源的 HR 等非技术人员，先不说这些人懂不懂技术，他们工作的性质，知识背景，看问题的角度都不一样。 每次在写文档前，我都会有个疑问，这里也想听听老师的看法。我在想要不要提前假定文档的读者。比如说我假定某个文档是给技术人员看的，基于这个假定，我可以使用一些专业术语，我还可以省略一些比较基础的概念，甚至是略去一些技术常识性的东西，这会大大降低我写文档的难度，让文档变得简洁，而且写文档的效率也可以提升，可这样的话这个文档的受众就变窄了，也不能帮助许许多多的非技术人员。反过来说，如果我对文档的读者不设限，那么我会对文档的结构仔细考量，对自己的用词再三斟酌，反复修改，换位思考，这肯定会花费我大量的时间，而且文档的内容会变的冗余，不方便自己和其他技术人员查阅，况且其他非技术人员也未必会看。有人会说，可以根据写的内容来决定呗，这有些时候说的通，比如 design doc 其实是给自己或项目相关人员看的，理清思路，搞清楚要做的事是最主要的。问题是，大部分时候，你怎么能提前判断你写的内容对其他人有没有用呢？就算一开始先写个简单版本的，如果别人觉得好，有意见的话我们再慢慢修改，如果没有就放着不动，或者按自己的需要来改，假定是给自己看的。有些时候并不是自己写的没用，而是别人不能一下子就理解，就不看了，我们也没法得到反馈，也不知道如何去修改。
作者回复: 你好， 我觉得你的内容可以作为本讲的补充，非常棒的思考，愿其他读者也关注到你的这些表达。 写文档需要假定读者的，也就是我们心中要有目标读者大致的画像，因为写给程度员读的文章很有可能就不适合产品经理。通过定位好读者，也能让自己要写哪些、不要写哪些会有一个判断的原则。显然，这一原则的存在也帮助我们把控写作的粒度——无论从深还是广上都有帮助。
2024-04-14归属地：美国1 
浅歌随风最近每两周要写一篇分享，个人的写文档现状是“想的太多、读的太少、写不出来”。会有很多想法，点子，但缺乏体系；输入的内容太少，缺少词汇、论点、论据，缺少好文章的样例；最终的结果就是写不出来。作者回复: 你好， 咳，这个过程咱都得经历，坚持下去会好起来的。这就好比你在爬坡了，翻过去就好了。 加油！
2024-04-01归属地：上海21
未来已来文档不会是一蹴而就的，肯定会根据自己对这一方面的不断了解和个人写作能力的不断提升而不断调整的，文档的质量刚开始不是最重要的，最重要的是将文档先生成，后期再不断调整完善。所以说要敢于写文档，只有产出了文档，那么写作能力才能慢慢的成长起来。作者回复: 你好， 你对文档的理解其实想表达的是“做中学”吧。是的，写文档不在于一上来要好，先将事情给说清楚就行，至于其他的手法、行文质量可以在后续对文档的优化中一步步学习、练习和完善。 说白了，与咱写代码是一回事，回顾咱的经历，自己写的代码三个月后去读，觉得“这谁写的代码，好乱啊”，一查commit log，“嚯，是我自己写的”，那赶紧改好来。 路走对了咱就不怕远。:-)
2024-04-01归属地：山东1
布谷我自己有几个问题： 1.不知道写什么 2.感觉自己写得不好，自己写的东西自己都看不下去。虽然尝试了很多方法，都坚持不下去。 比如碰到一个问题解决后想写一篇问题解决文档。问题解决完，写文档时发现还要再造一遍数据还原原来问题，再来解决一遍再写文档，想着还要花好多时间，心生抵触。 然后第二次再碰到一个问题时，想着要不一边解决一边写。发现这样要耗费好多时间。因为如果解决的问题复杂，本身要解决问题就已经够烦恼。解决完就已经到下班时间了。 还有一种情况，如果问题很简单，又感觉没有什么好写的。作者回复: 你好布谷， 你会有这些具体的烦恼是正常的，我也经历过。从我个人的成长经历来看，现在你最需要的是一次成功的体验，不过就会面临自己坚持不下来的这一绊脚石。我的建议是，找到自己写文档的价值，从这个点做些思考，想清楚自己为什么要写，给这事斌于一定的意义感，这样才能帮助个人建立起内在的力量来战胜过程中的困难。 在举措上，可以尝试从这几个角度做切入： 1）想清楚写文档对自己职业生涯的帮助。 2）将文档分享给他人而能帮助他人成长，从而找到成就感。 3）降低对写作质量的要求，因为做完比做完美更重要。 当咱动力不足时，确实没有其他更好的办法了。这就好比如果没有学习骑自行车的动力，那再怎么强调学会了的好都没有意义那样。也许《了不起的我》这本书值得你读，看是否能帮助你更好地做出改变。 我们一起加油！
2024-06-18归属地：福建2
Z有文档书写模版吗？作者回复: 你好， 文档模版取决于你的目的。我给一个概要设计的文档模版供参考哈。 【腾讯文档】概要设计 - 文档模版 https://docs.qq.com/doc/DVHNzZ0xoSkF3dmZt
2024-04-02归属地：福建