程序员文档工程师

1、 程序员成长系列之从程序员到文档工程师第一页，共二十页。从程序员到文档工程师 从某个角度看“程序员”这个称呼已经无法涵盖软 件公司中各种角色的职责和特点，成熟软件公司中会有 这个职位，但是在很多小规模公司中，文档工程师只是 一种角色，而不一定有职位设置。第二页，共二十页。程序员成长方向程序员软件设计师测试工程师文档工程师产品经理配置管理员项目经理第三页，共二十页。从程序员到文档工程师在国外，文档工程师是非常重要的角色，因为他要接受大量的、 高水准读者的考验，而且要跟踪不断创新的技术，感受产品周期 的压力，其重要程度不亚于系统分析员。以加拿大为例：同样四 年经验的系统分析员的薪水在￥55000；

2、而文档工程师为￥65000 属于专业职能，在技术移民中的评分为50，高于牙医、建筑设计 师，电机工程师（40）等工作种类。 然而在国内，人们的印象中，文档工程师还是属于低级“码字” 的角色，很多“真正的”程序员对此工作不屑一顾。不过随着软 件业的规范，国外先进软件开发方法的进入和推广，文档工程师 越来越受重视，在chinaHR51job等人才招聘网站，每星期都有 很多空缺。第四页，共二十页。从程序员到文档工程师 由于软件开发中项目繁多，输出文档的分散和更新 不及时，开发人员使用的工具多样化，多种版本和工具 并存种种原因导致开发过程中存在很多问题。部门主管 无法确切得知项目的进展情况，项目经理不

3、能准确掌握 各开发人员的具体工作，项目进展随意性较大；项目之 间沟通不够各个开发人员编写的代码风格差异，而且编 码和设计脱节。如果沟通不及时或被忽视，容易造成开 发工作的重复，留下大量难维护的代码；文档与程序严 重脱节，软件产品是公司的宝贵财富，代码的重用率是 相当高的，因此建好知识库是对公司优质高效开发产品 的推动。这些问题的解决都需要文档工程师的积极参与.第五页，共二十页。文档工程师的职责： 在RUP（统一软件开发过程）中，文档工程师负责 内部软件文档、用户手册编写及演示版本的制作，除此 之外，软件开发过程中的文档控制与规范也属于文档工 程师的职责范围。 实际上，在软件开发过程中，文档很难

4、单独存在， 它需要由文档工程师和开发人员共同完成。其中开发人 员扮演信息源的角色，文档工程师扮演一个信息处理中 心的角色，主要负责文档工作的质量。从程序员到文档工程师第六页，共二十页。收集/提出文档需求安排文档开发计划制定各类文档模板跟踪文档编写进度编辑文档文档的管理从程序员到文档工程师第七页，共二十页。收集提出文档需求： 对设计部门文档的需求来自项目外（客户，市场部 维护部门，其他项目等）或者项目内。文档工程师需要 有良好的沟通技巧。通过与客户和其他部门的交流，获 得他们在文档方面的需求，项目内的文档需求可以根据 软件工程的知识，由项目经理或文档人员自己提出。从程序员到文档工程师第八页，共二

5、十页。安排文档开发计划： 文档开发计划是在需求达到一定程度后，安排计划 编写的相应文档。文档开发计划的制定需要考虑目前开 发人员的开发任务，文档需求的紧急程度，文档编写的 难度等因素。所以文档开发计划的安排主要应该由项目 经理来负责，其中文档工程师起协助的作用。但是，如 果文档工程师对项目有足够的了解，计划草搞可以由文 档工程师制定，再由项目经理确认。从程序员到文档工程师第九页，共二十页。制定各类文档模板： 制定各种模板是文档工程师的主要职责之一，文档 模板和文档编写的指南对统一文档风格非常重要，因为 大部分的文档需要各个开发人员编写不同的部分，如果 没有统一的模板和明确的指南，很可能开发人员

6、提交出 风格各异，详细程度不同的文档，这给后期的编辑工作 带来了很大的困难，而且文档质量难以控制。 文档模板可以根据经验制定，也可以参考一些成熟 的开发模型如RUP提供的参考模板，删节修改后在项目内 使用。从程序员到文档工程师第十页，共二十页。跟踪文档编写的进度： 在项目经理确定文档开发计划，把任务分配给具 体的开发人员后，文档工程师需要不断的跟进文档编 写任务的完成状况。跟踪进度的工作可以通过一些项 目管理工具来辅佐。 从程序员到文档工程师第十一页，共二十页。编辑文档： 编辑文档就是对开发人员提交的原始文档进行合并 整理，修改，统一语言风格等工作。完成后，由文档工 程师初步检查一次，成为一份

7、草稿状态的文档，然后将 文档提交给相关的人员检查，如项目经理或CTO，其他 部门负责人等，检查人发现需要校正的地方，应该独立 做校正表，或者在原文档中做批注，而不应直接修改原 文档，最后的校正工作由文档工程师根据校正表或者批 注完成，成为一份核实状态的文档。在需要发布的时候 应该先对文档做评审，通过评审才能标识为发布状态。 测试人员可以认为是特殊的文档人员，负责编写编辑 测试文档。 从程序员到文档工程师第十二页，共二十页。文档的管理： 文档工程师应该负责：集中存储所有文档资料； 文档的变更管理；保证文档版域代码版本的一致性； 维护文档资料的索引表；配合IT人员定期备份文档 资料。从程序员到文档

8、工程师第十三页，共二十页。如何做好文档工程师 ： 要做好文档工程师的工作，首选要明确文档的价值所 在。从信息载体角度看，文档中记录的可能是杂乱无章的 数据，这些信息在某个项目或阶段完成后就无用了，同时 也可以通过提取信息中的知识，提高其价值，甚至可以变 成公司的资产。 软件文档分为内部文档和外部文档。内部文档主要是 用来做决策支持，外部文档一般指用户文档（主要是软件 说明文档）和客户文档（主要是需求文档）。文档工程师 只有了解这些，才能更好的看待文档的价值。从程序员到文档工程师第十四页，共二十页。文档工程师的工具： 文档工程师除了要学会利用Word、Ebook、Help、 Visio、Html

9、、Project Powerpoint、Acrobat等各种软 件，还要尽可能学会使用软件工程的软件来协助提高 工作效率，同时提高自身素质。从程序员到文档工程师第十五页，共二十页。文档的分类： 在软件开发中，需求定义、规格说明、开发计划、 使用说明、联机帮助等各种过程都会产生大量文档， 都需要文档工程师参与。有些开发方法甚至建议在编 码开始之前，用户文档就已经基本编写完成，这需要 文档工程师在文档管理方面有更专业的素质。 用户教育文档 客户支持文档 开发文档从程序员到文档工程师第十六页，共二十页。用户教育文档： 用户教育文档用于帮助用户认识产品，提供足够的指 引使用户能够安装、使用产品以及进行

10、一些必要的日常维 护工作。用户教育文档的结构和内容，应该在系统设计确 定后，就由系统实施人员开始设计，并且在整个开发过程 中不断的调整完善，最后和产品软件包一起，作为产品的 一部分，发布给用户。具体应该编写哪些用户教育文档？ 这没有统一的标准，需要首先分析清楚有哪几种用户，每 种用户围绕产品所必须要进行的一些活动。要得到这些信 息，可以参考开发文档中的需求分析文档。在分析出用户 和用户围绕产品而进行的活动得出一个必须编写的文档内 容列表，可以考虑根据活动的频率和相关性，将各部分组 合成若干份文档。从程序员到文档工程师第十七页，共二十页。客户支持文档： 主要包括项目管理文档、培训文档、需求分析文

11、档、 项目变更文档和批准书、基础数据准备和批准文档、软件 安装文档、软件客户化和二次开发文档、软件参数设置文 档、测试方案和测试结果报告、阶段成果确认书、会议纪 要、计划书及计划变更说明书等等。 客户支持文档主要包括系统更深层次的描述，更高级 的使用技巧等，具体应该包括哪些内容，可以在设计阶段 的可维护性设计时列出，也可以由维护部门根据以往的维 护经验提出需求。从程序员到文档工程师第十八页，共二十页。开发文档： 开发文档贯穿软件开发过程的各个阶段，在项目组 内可以分为 Requirement（需求），Design（设计）， Implementation（实现），Testing（测试），Release （发布），Communication（沟通），Management（管 理），Research（研究），Changelog（变更）和 Training（培训）几个大类。各大类下面可以根据实际 需要分为不同的子分类。从程序员到文档工程师第十九页，共二十页。内容总结程序员成长系列之。从程序员到文档工程师。件公司中各种角色的职责和特点，成熟软件公司中会有。之外，软件开发过程中的文档控制与规范也属于文档工。维护部门，其他项目等）或者项目内。制定各种模板是文档工程师的主要职责之一，文档。模板和文档编写的指南对统一文档风格非