做一个有温度的【互联网技术】学习小站，包括但不限于Java、Kotlin、Vue等主流技术分享。热血程序员永不服输，下一个目标：【全栈】。日拱一卒无有尽，功不唐捐终入海，关注我一起进步。
写文档重要吗？
作为一个程序员，你觉得，写文档重要吗？
个人认为会写文档，写好文档很重要且必要。
以下场景你是否似曾相识：
公司大行敏捷开发，需求急，任务重，文档容易忽视。于是出现了以下的对话：
领导：这个任务很急，是核心功能。你们先做好设计，避免返工。
几天后：
A：B同学你好，我的功能依赖你的接口，你的设计文档给我先看看，到时一起评审；
B：啊？！我每天事情很多，忙不过来，我直接口头跟你说吧，很简单的。巴啦巴啦…
A: 不行啊，这是核心功能，我们需要留下技术文档，评审一下看看方案如何，也是为了以后方便接手的交接。
B:敏捷开发，太忙了，没空，直接说吧。你熟悉这个模块，一说你就懂了。写文档太麻烦了。
A:……（内心：你可真是公司好员工）
在我们公司，面试官一定会考察应试同学的文档能力。询问工作中如何做沟通的，回答的方式有很多，有会议评审、当面提问、远程会议等等。
但是面试官想知道，这些沟通方式都是居于文档做前提的。如果产品经理PRD做的好，开发者测试者一眼能看懂，就会减少很多重复确认的次数。技术人员之间的沟通更是如此。架构师和技术负责人的文档能力要求更不必说。写好技术文档是非常重要的。
为什么呢？
程序员常说的一句话：我最喜欢写代码时不写注释，最不喜欢看看别人代码时没有注释。
没有文档比没有注释更让人觉得代码是一坨垃圾。没有文档的项目后来人根本没法接手维护，没有注释的代码会被问候，没有文档的项目会不会呢？
文档的作用
-
知识共享：技术人员编写的文档可以帮助传递和共享关键知识和信息。它们可以记录解决问题的方法、项目架构、代码库结构等。这样，即使在团队中有人离开或新成员加入，他们也可以快速了解项目的工作方式。
-
提高效率：文档记录了最佳实践、常见错误和解决方案，可以帮助其他人更快地解决问题。技术人员可以编写教程、指南和示例，以便其他人可以在需要时参考和使用。
-
沟通和协作：文档促进团队成员之间的沟通和协作。通过编写清晰的文档，技术人员可以更好地传达他们的想法、设计决策和项目要求。这有助于减少误解和提高团队的工作效率。
-
维护性和可维护性：文档可以帮助技术人员更好地理解和维护代码。它们可以包括关于代码结构、函数和类的描述，以及对代码中复杂部分的解释。这样，即使在未来修改或优化代码时，技术人员也能够更容易地理解和维护它。
-
知识管理：文档是知识管理的一种方式。它们可以成为组织中的宝贵资产，记录和保存组织的技术知识和经验。这样，组织可以积累并传承知识，避免重复工作，并在需要时进行参考。
总之，技术人员编写文档对于项目的成功和团队的协作非常重要。它们有助于知识共享、提高效率、促进沟通和协作，并支持代码的维护性和可维护性。
如何写好文档
好的文档需要长篇大论吗？
不需要，追求同事花最少得时间理解你的描述，多用图：时序图、流程图、架构图等，一眼能看懂你的表达。
以下是一些写好技术文档的技巧：
-
明确目标受众：了解您的目标受众是撰写技术文档的关键。确定读者的技术水平和背景，并相应地选择适当的语言和内容层次结构。根据读者的需求和背景，提供足够的上下文和解释。给技术看的技术文档，给用户看的操作手册区别很大的。
-
清晰的结构：确保您的文档结构清晰且有层次。使用标题、子标题、段落和列表等来组织信息。考虑使用目录或导航帮助读者快速浏览和定位所需的内容。
-
清晰简洁的语言：使用简洁明了的语言表达技术概念，避免使用过于专业化的术语和缩写（统一语义）。使用简单的句子和段落，并避免冗长的句子。
-
提供示例和代码片段：示例代码是理解技术概念和实现的重要工具。提供清晰、简洁的示例代码，并解释关键部分的工作原理和用途。确保示例代码可供读者直接使用和测试。
-
图表和图形化表示：使用图表、图形和图像来辅助解释和展示技术概念。图表可以帮助读者更好地理解流程、架构和关系。确保图表清晰、简洁，并提供必要的标注和解释。
-
引用和链接：在文档中引用其他相关文档、资源或参考资料。提供链接或引用，使读者可以进一步查阅相关信息。确保链接有效，并在文档中提供足够的上下文，以便读者理解链接的内容。
-
更新和维护：技术文档应该与项目的发展保持同步。要求同步修改。
-
使用合适的工具：选择适合您的需求的文档撰写工具。这些工具可以提供格式化选项、版本控制、团队协作和导出为不同格式的功能。一些常用的技术文档工具包括Markdown、PlanUML等。工具用来提高生产效率，比如代码画图而不是用在线工具拖拉调整费时，我们不需要追求美观。
自己怎么进步文档写作能力？
学习MarkDown、PlanUML等工具的基本使用。
自己多做笔记和总结，温故知新。可以自己弄个博客/公众号/做个自己的文档库等。用来管理或分享自己的总结，强迫自己去动手写。
“借鉴”优秀的文档，多做多练。
对自己的文档要求严格，长期积累有益无害。我入职这家公司，因为我自己平时写公众号的文章，加了不少分。
文档先行，做需求，先把文档做好，文档做完，整个流程和思路已经了然于胸，写代码可以避免返工，更高效。
做一个有温度的【互联网技术】学习小站，包括但不限于Java、Kotlin、Vue等主流技术分享。热血程序员永不服输，下一个目标：【全栈】。日拱一卒无有尽，功不唐捐终入海，关注我一起进步。