文档开发流程

随笔-5  文章-0  评论-0 

 

 

用户手册开发（一）-文档开发流程

 

      最近，公司的重大项目快完工了，除了留下一些Bug，还留下了一些收尾工作，比如我今天要讲的文档。在会上，经理说，怕研发人员写文档写不好。不论经理有没有说包含激将之意的言语，写文档都是一项挑战性的工作。
 
文档开发流程
 
    网上并没有给出一个比较完美的文档模板，如何写这个文档呢？写文档不能简单的看作写一篇文章。它也与软件开发一样，有一个逐步完善的流程。这是我写文档过程中的流程：
 
 
 
图1 文档开发流程
 
1. 确定条件和背景。
 
      在文档开发的最初阶段需要了解文档写作的内、外部的条件和背景。不同的专业存在不同的专业背景，对于专业软件不是按照一个文档模板，就能把所有的文档写出来。
 
文档写作的内部条件：
 
    （1）公司的产品是大型机械设备的状态监测的软件，软件中有许多图谱和报表，用于显示状态监测的数据。软件的专业性体现在图谱和报表中，而非软件的操作当中。
 
    （2） 当前软件的可运行的版本并不是稳定的版本，写出来的文档必须符合稳定版本的软件的内容。当然存在一种情况，那就是后面的一个版本（也就是正在做的版本）是一个用户界面比较完善的版本。
 
      开发人员需要对当前软件所处的状态做出一些总结，以便在写文档时，给自己做出指导。
 
文档写作的外部条件
 
    （1）用户群体的认识。用户主要分为几种：工程人员、销售人员、专业人士。在这些用户当中，我们更关注衣食父母-专业人士。对于专业人士，查看图谱和报表是他们的强项，而他们将面临的是一个新的软件，他们需要的是培养一些新的操作习惯。
 
    （2）文档的最终形式为打印稿。这些专业人士，很多都是经验丰富的老专家，写出的文档需要照顾到老专家们的视觉感受。
 
     这些外部条件是开发人员所容易忽视的，却是经理们所清晰了解的。在开发之初我的经理们就把这些信息在话语中透露给大家。
 
    了解文档开发的内、外部条件，能让我们在文档开发当中，找到一个大的方向。没有找到大方向，很容易剑走偏锋，比如：我花很大的力气来写图谱的内涵，而这是专家所熟知的，到头来说不定，我写的有很多错误、不够详细。
 
 
 
2. 明细要求和准备资源
 
     写文档之前，明细各项要求，才能写出优秀的文档。什么样子才能算优秀的文档呢？这个很难说，但是如果要说你见过哪些狗血的文档，你可以马上大量吐槽：
 •·××，居然还有错别字！
 •·黑压压的一片（文字），看都不想看。
 •·啥文档？找了半天，这个设置功能就是找不到。
 •·我发下这篇文章不适合新手。
 
    细数这些吐槽的片段，作为文档的作者不得不小心翼翼了。文档的明细要求来自于文档的不同的用户。
 
 
 
    经理在文档出来前，提出的模糊要求：
 
（1）文档要符合用户操作。一般我们阅读是从左到右，从上到下。
 
（2）写出清晰、完整的文档。
 
（3）能让用户快速入门。
 
（4）写出的文档可操作性要强，不能出现告诉别人一个功能，而他不知道如何才能达到这些效果。
 
 
 
    经理在文档出来后，提出的苛刻要求：
 
（1）这些文档格式不统一。重写！
 
（2）段落结构混乱。重写！
 
（3）归纳的重点偏离。重写！
 
 
 
    测试提出质量要求：
 
（1）完整性。界面上的功能点，都需要写出来。不能却胳膊少腿。
 
（2）准确性。准确描述功能，给出的步骤能让测试人员实现，并达到预期的效果。
 
（3）优美性。格式优美，结构清晰，看上去舒服。
 
 
 
    自己的要求
 
（1）快点写完这文档。
 
（2）写好点，别让我重写，别被吐槽。
 
 
 
    用户的要求
 
（1）快速了解内容
 
（2）查看感兴趣的部分。
 
（3）帮助解决问题。
 
（4）能看懂。
 
 
 
    在操刀动笔之前，必须做好准备：
 
（1）选用一个界面完整的，且不会再做其他修改的软件版本，作为截图的来源。
 
（2） 软件的数据必须接近真实。
 
      （3）问问工程人员与销售人员有没有前一版本的文档。
 
 
 
3. 提纲。
 
      提纲构筑了整个文章的骨架。按照模板写或者按照前人的模式写，容易让文档缺乏条理。使用提纲，能让文档章节分明，结构清晰，内容详细而充实。下图即本文该章节的提纲的一部分（该图使用的软件是MindManager）：
 
 
 
图2 提纲
 
    在提纲中划分了章节和细化了一些要点，有了它之后，一篇完整的文章就填满心中。
 
 
 
4. 编写与审阅。
 
     第一次编写是依据提纲来完成的。如果要添加内容，则先在提纲上做出修改，再修改内容。第一次编写内容，要求做到完美比较难。在写的过程中会遇到各式各样的问题，使用Word的批注来记录面临的问题，写完段落回过头来再修改。
 
     审阅即自己对文档的测试，查找文档是否满足明细的要求，审阅完马上修改。
 
     编写文档过程中重要的一点时，当写完前面的两三个章节时，马上拿给经理（有经验、了解客户的、了解业务的经理，如产品经理）看并让他做出指导。经理手握文档的生杀大权，同时他会告诉你，他需要什么样的文档。如果不这么做，有可能在自己折腾一番之后，重写文档。
 
 
 
5. 测试。
 
    在审阅完之后，提交测试。自己的多次审阅会产生精神疲劳，由于心中非常熟悉文章的思路，我们会快速浏览文章，而忽略很多不足的和错误的地方。我在第一遍之后，测试部测试的结果主要是一些地方写的不全，一些地方出现了错别字。
 
 
 
6. 修改与审阅。
 
    面对测试部提出的Bug，做出修改和完善。当然，这次我做出了更加仔细的检查，以保证无错别字的情况。
 
 
 
7. 测试、完善并提交。
 
 
 
文档工作量的划分
 
    写文档是一项较为繁重的工作。下面有两种写文档的流程：
 
    第一种是传统的办法：
 
（1）写整个文档。
 
（2）测试。
 
（3）修改和完善。
 
    这种方法是脑子中默认的流程。但在实际操作的过程中，会出现一些问题：
 
（1）工作量难以估计。什么时候才能完成这个文档？经理在问，测试也在问，自己也在问？
 
（2）其他人无法看到当前的进展。研发、产品、测试经理希望尽早看到成果，哪怕是一部分。每周立会上，整个文档没有写完，研发人员该如何交差？
 
（3）开发风险大。开发人员不能尽早知道其他人（测试、产品、工程等部门）各项详细的要求；若写完整个文档，被测试部打回来了，全文都得重写；经过多轮迭代，会浪费研发、测试更多时间，可能会延期提交文档。
 
 
 
    第二种是划分工作量的流程：
 
（1）写提纲，并审阅。
 
（2）根据提纲中的章节划分为多个任务，每个任务走1. 文档编写2.提交测试3. 修改完善的流程。
 
    划分工作量的流程相比传统的流程，有十分明显的优势：
 
（1）在迭代周期内能输出部分文档。
 
（2）任务划分明确，能得到清晰的进展。
 
（3）降低了文档开发的质量和时间上的风险。在文档开发初期，通过经理和测试人员的把关，产出高质量的文档。
 
（4）切分了章节的耦合度，让文章质量更胜一筹。
 
    不足之处：不能完美地解决工作量的问题。