如何写一份技术文档
常用的模板
what 什么是模板
模板看起来像是一堆场景，每个场景点开里面有一系列内容。里面的内容一般是写作的整体框架确定场景下，哪些关键内容需要在文档中输出，并提供一些推荐的表达方式，因此，我们很容易定义模板，这些东西很简单
why 为什么需要使用模板
想象这样一个场景你需要组织一次团队 outing，你已经做好了功课，现在需要输出一个计划给大家看。因此，你需要收集大家的意见，以及大家想要了解的内容等等
那么，如何确定你是否遗留了什么呢？这时，如果你有一个 outing 的模板 那么模板上会告诉你，你需要提供时间表，关键人物和团队的联系方式等等，还需要提供交通方式、酒店、景点特色、行程等等，根据模板来写，这样就能轻松很多，因为你不必重复思考，只需要像做填空题一样，把他们全部填完就行了
这也是我们使用模版的原因，因为模板吸取了大量前人的经验，来帮助你减少重复思考的过程
how 如何使用模板
作为技术同学我们经常使用的几种模板，我们来一个一个看
工作周报
工作周报一般分为本周的重点和下周的计划，以及你的思考。本周的重点，又包括任务进展相关的数据、风险、甘特图等等，比较推荐使用甘特图或者日历来表达进展。
主播的核心内容是你与主管的沟通，或者与同事的沟通。你需要在周报中体现，你这周做的怎么样？计划什么时候做某事，下周什么时候做某事是否一切正常，是否有风险，需要协调解决等等。
一份好的周报，能让你的同事知道你在做什么，能让你的主管知道你在做什么，以及你是否需要帮助等等。
系分文档
细分文档，你最先需要确定是范围，确定范围，也就是明确需求或分析需求
。接下来是系统设计，在系统设计的时候，你需要先分析现状，我们有什么，我们可以做什么，然后再进行架构的设计，架构设计完成后，你需要进行系统的建模，就像施工时候的图纸，有了施施工的图纸，我们就可以得到测试的策略，最后我们需要一些附录的资料。
有时候附录的资料非常重要，大家经常会忽略。有了附录的资料之后，我们经常会需要给出一个时间表，告诉我们什么时候开始，什么时候结束。在某个关键节点，我们需要达到什么里程碑。
接口文档
这口文档是我们技术同学经常要出示给合作伙伴的，比如你是后端同学，那那么你就需要给前端同学出示一份接口文档。接口文档在几种文档中算是比较简单的，也比较死板。
你需要请求什么路径，发什么报文，你能得到什么东西。这面比较重要的一点是，接口内有些特殊需要注意的点，如果你需要告诉前端，建议你能写下来的话就把它写下来，你省下来的内容，一般最后都需要多次的反复沟通，所以为什么不最开始就写下来呢。
技术方案文档
技术文档不仅是评审时与小伙伴们一起看的，也是主管一起看的。
他的内容形式比较灵活，但是里面有几个比较重要的点。第一点，也就是大家经常容易忽略的需求的背景，这个非常重要。
很多人经常漏写。作为技术人，你需要了解你所做产品的背景和原因。因为你如果没有想清楚，你可能会做出不符合用户需求的产品。因此，这需要一个思考的过程。之后就是系统现状的梳理以及竞品的分析。很多时候我们可以看一看其他相似的产品在做什么。
之后你需要进行领域模型的分析。因为领域模型需要你清楚的了解你所涉及的关键要素以及它们之间的关系。
关键的交互流程需要突出体现，系统，不能只关注自己，也需要考虑上游和下游自己的故障，会对别人有什么影响，这些东西都需要呈现给合作伙伴，避免在维护的时候出现问题。
其他类型的文档
其实文档写多了之后，我们最终都会变成无招胜有招，并不是每一篇文档都需要模板，重点是养成一个习惯，先定框架再写内容，而不是直接开始写流水账，你也可以沉淀自己的特色。
模板并不意味着只有公开的模板可以使用，一份模板意味着你们你或者你的团队思考和处理问题的方式，这些将影响你的团队的文档质量。
常见的表达方式
提高文档可读性的技巧
使用换行、缩进、高亮、代码块和表格等方法，可以显著提升文档的可读性和理解度。层次分明的结构、突出的重点部分以及代码的规范展示，都能有效引导读者快速把握内容要点
思维导图与技术表达图：高效沟通的工具
思维导图作为最接近人类思维的模式，通过分类学过程展现思想结构，便于读者按需寻找信息。技术表达图，如序列图、类图、组件图和状态图则分别用于描述用户请求过程、类间关系、系统组件及流程走向，以图化形式替代千言万语，实现高效沟通。
多样化表达，增强文章的可读性
在表达项目进度时，甘特图是一种常用工具，它明确了时间轴并展示任务间的关联。此外，还可以使用不规范的图形，如总览流程图和象限图、结合段子、梗图、表情藏头诗等多种表达方式，以提高文章的可读性和趣味性
推荐的工具
探索 Markdown，提升写作效率与文章结构
Markdown 是一种易于使用的标记语言，通过简单的符号表示文章的结构和格式。它使得文章的编写、阅读和共享变得极其方便，尤其适合基础文档和博客文章。Markdown 的纯文本性质，使其成为跨平台协作的理想选择。且其简洁的语法式的非专业协作者也能快速上手。此外，Markdown 还支持表格引用和代码块等富媒体元素，极大的增强了文本的表现力和可读性。
高效写作与图形绘制 drew.io
文本绘图
plantUML文本绘图作为一种高效的技术文档创建工具，无需担忧排版问题，可以直接基于文本描述来构建具有固定结构的图形，这对于技术人员来说尤其有益，因为这样可以专注于内容而非排版。此外，文本绘图还具有易于共享和编辑的优点，能够降低团队成员之间因编辑冲突而产生的问题。
参考资料
本文来自 古权 的内部分享