如何写好软件文档
不写文档会挨骂，写烂文档更挨骂，写好文档，才能少挨骂。
动笔之前
明确受众
开始动笔之前，先问领导与自己：文档是写给谁看的？
受众不同，文档的侧重点也要有所不同。
写给技术人员，文档的语言要尽可能精确，而且要明白他们关心的是什么内容。例如同样是写接口手册，开发人员文档要把重点放在接口规范方面，而运维文档要把重点放在接口服务的监控与维护方面。
写给用户时，文档的语言要直观，不必特别精确，能用通俗的语言描述，就不要用技术的语言描述；能用结构示意图、流程图、折线图、条形图、饼图等图片形式描述，就要避免用密密麻麻的文字描述。总之要让新手看得懂。至于特殊情况，能不提就不提，毕竟正常情况他们还不一定能看得懂呢。
明确形式
要确认好文档以什么形式展现：设计文档、操作说明书、汇报PPT？
特别是刚参加工作、没写过文档的新人，经常会犯些低级错误——明明让写需求文档，把系统具体实现写进去了；让写操作手册，却从需求文档复制粘贴，写了一堆业务规则，看完仍然不知道系统该点什么按钮；让做PPT，页面文字密密麻麻，别说投影，看屏幕都觉得累……
除了文件的格式，内容也要考虑好形式。例如设计文档要重点讲系统的功能实现，而操作说明书则要避免提及系统的内部原理，重点讲用户眼睛能看到的外部现象。还有技术文档要关注细节，而商务文档要注重表达形式，弱化细节。
确定结构
俗话说“磨刀不误砍柴工”。写文档的时候，也不要直接动笔，先“磨磨刀”，确定一下文档的结构，把地基打牢以后再继续填充材料。
在学生时代的语文课，老师肯定教过大家说要按“总-分-总”结构来写作文。不光语文作文如此，学术论文和软件文档也是一样。
写作文要先确定主题立意，然后再根据主题展开表达。写文档也是如此，“总”应该按以下结构和顺序来写：
- 总述：使读者了解文档的主题、目的、适用情况等。
- 分述：按照总体架构、总体流程等顺序，对主题依次进行介绍。每部分内部也按照“总述-分述”的模式进行叙述。
可以用以下三种方法来建构文档。我们以软件设计文档为例：
先建立结构，再填充细节
我们对上面提到的“总述”和“分述”进行分解：
很显然这样是不够的。我们继续挑其中一个点（功能设计）继续分解：
这时不用急着填充内容，先参照国家标准和其他现有文档，把“应该有什么内容”梳理出来，力求覆盖全面。当然这个工作不是必须一次性独立完成的，可以先形成一版，然后让领导同事帮你查漏补缺。
确认无误后，就可以按照这个结构开始填充内容了。
先整理素材，再形成结构
我们从另一个角度来考虑系统设计：
假设设计面向社会用户的“xx证申请”功能，那么这个功能需要考虑以下方面：
整理出来之后，需要进行一个取舍，哪些是要写进文档的，哪些是不适合写进文档的（离题或者过于细节），然后整理出一个结构：
总结出结构后，按照规范的文档的结构进行调整，该功能设计的初稿就差不多了。
综合运用以上两种方式
写作方式不是一成不变的。在写作过程中，要时不时地改变一下视角，在整体结构与局部细节之中切换，同时也在上述两种工作方式之间进行切换，从两个角度分别进行“进攻”，否则的话容易产生两种极端：
- 长时间关注整体结构，会导致内容叙述得不够细致。内容面面俱到，而细节叙述不足，难以指导具体工作。
- 长时间关注局部细节，会导致整体逻辑不清，使读者需要费一些精力才能“入门”。
另外建议善于利用思维导图工具，维护写作思路。
编写之中
表达准确
即使不使用精确的技术语言，语言表达仍然要保持准确，以免产生分歧。
准确地领会任务目的
当领导在微信里发了一句“写清什么功能在哪里如何实现”，实际上你收到的是一个含糊的要求，需要与领导进行确认：这个要求的目的是什么？“哪里”是什么含义？指的是一个功能模块，还是一个操作步骤，还是一个文档的位置？“如何”又是什么含义？是某一套开发框架，还是一套业务流程，还是一句简单的“用Java开发”？
避免模棱两可的语言表达
例如“接口”，是指Java的interface呢，还是后端调用的API呢，还是浏览器调用的API呢，还是指用户输入输出的界面呢，或者是物理的插头插座？如果无法从上下文看出接口具体在指什么东西，那么就要界定好“接口”的具体含义。
除了模棱两可的话，还要避免“正确的废话”。例如“该接口应当在需要的功能中进行调用”，道理正确，在开发规范中写这句话没问题，但是在设计文档中写这句话就不具备可操作性——“需要的功能”有哪些？如果没有该怎么办？难道是“不应当在不需要的功能中进行调用”吗？当然解决方法也简单，就是要“具体”，明确哪些功能是“需要的功能”，举出实际案例，这样这句话就有意义了。
注意符合目标读者的语言体系
面向用户的文档，要更加注意匹配用户的语言体系。例如，开发政府系统，文档和界面用词就应当规范、严谨、死板，你把“报备”误写成“审批”，虽然在系统实现上都是把数据库表格里的CURRENT_STATE字段给UPDATE成完全相同的字符，没有任何技术上的区别，但在用户眼里这就是一个设计缺陷，因为“报备”和“审批”是两种性质完全不同的操作，具体来讲，在系统之外的人工流程，以及用户在点击操作按钮之后需要承担的责任都是不一样的。
注意规范
团队通常会制定文档模板和规范，有些文档还受国家或行业规范制约。开始编辑之前，先找领导同事要一份现成模板，然后再动手。不要随便自己找模板，不要违反文档规范。
文档要特别注意格式！例如：
- 不要有错别字
- 英语单词拼写要正确，例如是MySQL而非mysql、MySql、MYSQL
- 标点符号要正确，特别是不要在中文中使用英文标点
- 字体、字号要统一
- 不要有多余空白
- 该对齐的地方要对齐
关于格式方面的规则，可参考阮一峰《中文技术文档的写作规范》。
完成以后
先完成后优化
刚刚走出校园就进入职场的新人容易犯一个错误：总想着把工作做好再提交。
这正是职场大忌！假如你不熟悉工作，又没有及时与领导沟通，等你费尽九牛二虎之力勉强在deadline之前完成，领导却发现你写出来的东西根本不符合要求，那时候领导的心情一定是非常激动的，你以后的工作也会充满（负面）挑战。
工作质量很重要，用合适的方法按时完成同样重要。特别是职场新人，干活应当这样干：
- 接到任务后，先稍微想一下整体思路，和分配任务的领导确认一下自己思路对不对。
- 不定期跟领导反馈自己做得怎么样，遇到问题及时找领导同事问。
- 不要糊弄，但是也要优先保证总体进度，先把“垃圾”堆出来，做出一个大体上说得过去的东西，然后再优化细节。职场上很难弄出完美的东西，只能是不断优化，早点把垃圾堆好，优化的空间就相对大一些。（本条不适用于纯粹压榨人的公司）
再强调一下，别怕挨训，就算挨训，在过程中挨训比到最后才挨训要好得多。
多读、多改
初稿肯定会有不少语文方面的问题，句子不通顺，语义不清楚，前后逻辑不连贯。因此，写完之后要通读文档，PPT的话还要试着讲一下，将整个文档顺一顺，大小毛病改一改，然后再从头检查一遍，重复以上几个步骤，直到大体满意为止。
直接提交不行吗？当然不行了！明明是自己能挑出来改好的低级错误，却放着交给别人检查，这就是在浪费别人时间，而且会让人觉得你工作态度不好。虽然你努力完善的结果可能也是返工，但返工原因由低级的格式问题变成高级的业务问题，至少不会让人太扫兴。
管理提升
版本管理
文档应做好版本管理。
即便无法版本管理（例如净是些照片、Word、Excel、PowerPoint文件），至少要有个固定地方集中存放，而不是乱七八糟散落在邮箱附件、微信聊天记录、QQ群文件、张三电脑C盘、李四电脑D盘……特别是与外界沟通协调的文件，如果不集中管理，日后需要追查记录时便无处可寻，让人觉得管理混乱。
文档要分门别类存放。就算要偷懒，至少文件名要有个规范（包含关键词、日期时间等），不要“QQ文件1231231231.doc”、“预算.xls”，免得日后找不到。另外也可以考虑使用Everything等文件搜索工具来查找文件。
对于内部开发文档，个人提倡使用纯文本与Markdown格式，不要使用Word格式。Word格式需要浪费时间排版，难以搜索，而且很难管理版本，而Markdown格式简洁明了，便于全文搜索，并且可以直接扔到SVN/Git仓库里面进行版本管理。
文档发生重要改动，如需求变更、用户确认结论等，务必记录修改时间和修改原因，并做好变更管理（例如commit message），以便日后追查。受影响的程序代码也要用注释和提交信息加以说明。
提倡在编写过程中使用在线文档（例如石墨文档、腾讯文档），或者使用一些专门的文档/知识库软件，例如ShowDoc（在线版、本地部署版）。这类软件操作方便，适合团队协作维护文档，又有版本管理功能，可随时检查修订记录。
文档要随时维护，不要攒着
当用户需求、功能设计、接口规范、数据库结构等信息发生变化时，务必及时更新相应的文档。今天不把文档维护好，明天会有新的事情来烦扰你，让你更没有心思管文档，日积月累，最终变成一个大坑。
建议在小组安排一个专门的文档人员，在有人往工作群丢文件的时候，他/她能默默地把文件收集整理好。当一项阶段性任务完成的时候，也能把团队成员工作的素材给整理好。
如果没有专门的文档团队，那么在管理项目时应当将文档也作为开发任务之一来管理，将光写代码（特别是变更了设计的代码）、不维护相关开发文档视为没完成任务。
当然现在已经是内卷的时代，能把工作卷完就已经很难了，所以即便无力将文档维护到最新，至少要维护一份比较规范的备忘录，指出文档哪个地方与实际不符，文档希望按A实现而实际上已经按B思路来做，然后再对备忘录进行统一的版本管理，这样总比什么文字记录都没有强。
平时抽空练习练习
很多技术人员的语言表达能力不强，虽然大佬心里清楚他是什么意思，但是一般萌新却难以理解。建议大家去CSDN、GitHub等网站开个博客，或者去知乎问答编故事，用长篇回答装装逼，提高自己的语言表达能力、搜索资料的能力与整理信息的能力。