技术文档的表现力.PDFVIP

目錄 写在前面 1.1 开始 1.2 本文讨论的范围 1.2.1 从Hello World开始 1.2.2 展开 1.3 文档的要素 1.3.1 文档的读者 1.3.2 文档的组织 1.3.3 设计文档的粒度讨论 1.3.4 什么时候应该画图 1.3.5 几种典型的图的画法 1.3.6 关于标准UML 1.3.7 一些经典案例的表现手法分析 1.3.8 1 写在前面 写在前面 作为一名软件架构师 ，在工作期间发现一个另我有些诧异的问题 ：很多人是不会写设计文档 的 。勉强写出来的文档一般有如下几种情况 ： 1. 写出来的东西没人能懂 ，和没写没有什么区别 ：比如我这个系统使用了spring mvc框架 ， 云云 2. 把设计文档写成需求文档 ：画了一堆的业务流程 ，就是没谈怎么实现这些业务流程 （这 才是设计文档啊） ； 3. 文字堆叠 ：该有的差不多都有 ，就是组织上杂乱无章 ，要么非常考验读者的耐心 ，要么 考验读者的记忆力 （在一个角落里面阐述了最核心的问题 ，你需要记住） 为此 ，我做了诸多的努力 ，帮助大家能够把这方面的能力提升上来 。在此过程中 ，我针对文 档的作用 、关键点 、技巧等也做了一些思考和沉淀 ，想把它记录 、整理出来 ，与同行共享 、 共勉 。 2 开始 一个关于文档的故事 记得我还在一家日资公司工作的时候 ，那时候刚工作一年左右吧 ，该公司每半年举办一次技 术发表会 ，选择公司一些”有为青年“ ，在一个较为公开的场合发表 。我”有幸“被选为所谓的有 位青年之一 ，当然 ，需要做一个PPT 。我之前做PPT的经验还停留在学校阶段 ，所以我第一个 版本PPT很快且很烂地做出来了 。提交给一个高层主管看 ，结果被批的面目全非 ： 主管 ：”这 一页PPT ，你到底要说什么？“ 我 ：我想说的是XXXX 主管 ：那为什么起这个标题 ？ 写这么多 字谁会有耐心看 ？ 我 ：回头修改 。 如此反复了好几遍 ，我记得改了3~4个版本吧 ，有一天刚好他有点时间 ，可能心情也不错 ，就 给我”现场指导“了 ，就是他一边画PPT ，一边给我讲 。我马上有一种豁然开朗的感觉 （现在我 给别人指