科技文档写作实务 人民邮电出版
出版日期:2013-8-1
ISBN:9787115320742
作者:中兴通讯学院
页数:187页
内容概要
《科技文档写作实务》以“理论+实战”的方式，帮助读者在短时间内掌握科技文档写作要领，提高职场竞争力。全书系统地阐述了技术文档的概念、写作流程、质量要素及典型技术文档的写作方法。为了帮助读者更好地掌握这些原理，《科技文档写作实务》针对实际工作中经常使用到的需求说明书、概要设计、软件模块详细设计、测试用例、使用指导和故障处理进行专题介绍，从内容框架、写作过程、写作实例、写作要点和常见问题进行了详细说明。
《科技文档写作实务》既可作为产品研发和测试人员、售后支持人员及用户文档开发人员的培训参考用书，也可作为高等院校的教学用书。
亚马逊上有
书籍目录
目 录
1 概述篇 1
1.1 什么是技术文档 2
1.1.1 技术文档的定义 2
1.1.2 技术文档的范畴 2
1.1.3 技术文档的特征 4
1.1.4 技术文档的多种形式 4
1.2 技术文档写作的国际国内现状 5
1.3 技术文档写作的重要意义 6
2 基础篇 7
2.1 技术文档写作流程 8
2.1.1 需求分析 9
2.1.2 架构设计 10
2.1.3 文档写作 10
2.1.4 质量控制 11
2.1.5 文档发布 12
2.1.6 文档交付 12
2.1.7 文档维护 12
2.2 需求分析 13
2.2.1 信息收集 13
2.2.2 简化归类 15
2.2.3 分析需求 18
2.2.4 确定文档开发任务 20
2.3 架构设计 21
2.3.1 架构前的准备和学习 21
2.3.2 设计架构 22
2.3.3 架构检查 25
2.4 文档写作 26
2.4.1 写作的逻辑 26
2.4.2 写作6步法 28
2.4.3 写作黄金法则 28
2.5 质量控制 31
2.5.1 质量控制活动 31
2.5.2 高质量文档三要素 34
3 进阶篇 37
3.1 实用性 38
3.1.1 安全第一 39
3.1.2 内容准确 41
3.1.3 面向任务 45
3.1.4 合理组织 49
3.1.5 内容完整 58
3.2 可读性 61
3.2.1 易读 62
3.2.2 易理解 75
3.3 舒适性 85
3.3.1 文档获取便捷 86
3.3.2 内容检索高效 87
3.3.3 阅读感受舒适 92
4 实战篇 101
4.1 如何写需求说明书 102
4.1.1 需求说明书简介 102
4.1.2 需求说明书内容框架 102
4.1.3 需求说明书写作流程 104
4.1.4 需求说明书写作实例 106
4.1.5 需求说明书写作要点 111
4.1.6 需求说明书常见问题 111
4.2 如何写概要设计文档 112
4.2.1 概要设计文档简介 112
4.2.2 概要设计文档内容框架 113
4.2.3 概要设计文档写作流程 114
4.2.4 概要设计文档写作实例 117
4.2.5 概要设计文档写作要点 121
4.2.6 概要设计文档常见问题 121
4.3 如何写软件模块详细设计文档 123
4.3.1 软件模块详细设计文档简介 123
4.3.2 软件模块详细设计文档内容框架 123
4.3.3 软件模块详细设计文档写作流程 124
4.3.4 软件模块详细设计文档写作方法 125
4.3.5 软件模块详细设计文档写作要求 131
4.4 如何编写测试用例 144
4.4.1 测试用例简介 144
4.4.2 测试用例内容框架 144
4.4.3 测试用例写作流程 146
4.4.4 测试用例写作实例 148
4.4.5 测试用例写作要点 152
4.4.6 测试用例常见问题 152
4.5 如何写使用指导文档 155
4.5.1 使用指导文档简介 155
4.5.2 使用指导文档内容框架 155
4.5.3 使用指导文档写作流程 156
4.5.4 使用指导文档写作实例 157
4.5.5 使用指导文档写作要点 171
4.5.6 使用指导文档常见问题 171
4.6 如何写故障处理文档 173
4.6.1 故障处理文档简介 173
4.6.2 故障处理文档内容框架 173
4.6.3 故障处理文档写作流程 174
4.6.4 故障处理文档写作实例 177
4.6.5 故障处理文档写作要点 179
4.6.6 故障处理文档常见问题 179
5 附录 主题类型 183
5.1 概念(Concept) 184
5.2 任务(Task) 185
5.3 参考(Reference) 186
作者简介
《科技文档写作实务》以“理论+实战”的方式，帮助读者在短时间内掌握科技文档写作要领，提高职场竞争力。全书系统地阐述了技术文档的概念、写作流程、质量要素及典型技术文档的写作方法。为了帮助读者更好地掌握这些原理，《科技文档写作实务》针对实际工作中经常使用到的需求说明书、概要设计、软件模块详细设计、测试用例、使用指导和故障处理进行专题介绍，从内容框架、写作过程、写作实例、写作要点和常见问题进行了详细说明。
《科技文档写作实务》既可作为产品研发和测试人员、售后支持人员及用户文档开发人员的培训参考用书，也可作为高等院校的教学用书。
发布书评
精彩书评 (总计1条)
-
近日，笔者入手了中兴通讯学院编著的《科技文档写作实务》一书。在这之前，国内基本上没有与技术文档写作领域相关的专业中文书籍，应该说这本书还是很有意义的。本文将对此书进行一番简评，供大家参考。从书名来看，“科技文档写作”显然是一个范畴更大的概念，并不仅仅局限于笔者所从事的技术文档写作领域。实际上，这本书包含了两大方面：1）研发文档写作；2）用户文档写作。除了第四章“实战篇”用了较大篇幅讲解研发类文档（需求说明、概要设计、测试用例等）的撰写外，其他章节都是通用的知识。由于笔者仅关注技术文档写作部分，因此本文不对此书中的研发类文档相关内容作出评价。从此书中用到的技术文档写作内容组织方式来看，明显是运用了DITA的理念，虽然作者没有明确提到这一点。DITA全称是Darwin Information Typing Architecture，中文名叫“达尔文信息类型化体系结构”，近年来在国际上的技术文档写作领域很流行，尤其是在大公司中，以DITA为基础的各种商业出版解决方案应用非常多。DITA将文档主题类型划分为概念（Concept）、任务（Task）和参考（Reference）这3种：概念概念主题回答“是什么”的问题，提供读者能成功操作、维护、使用一个产品或者界面所必须知道的背景信息。任务任务主题回答“如何做”的问题，通过Step by Step的方式描述完成一个特定任务所需的方法和步骤。参考参考主题用于描述产品或技术中特性结构比较一致的主题，如语法规则、消息说明及参数说明等。DITA还有其他一些特性，感兴趣者可以自行Google一下相关的资料。中兴和华为这类国内通讯巨头应该都是采用了DITA解决方案来组织技术文档出版的。至于对待DITA的态度，笔者觉得我们也不必过度推崇，大公司采用它，自有其道理，但是中小公司未必也一定要上DITA方案。毕竟，使用开源方案的话，没有一定的技术支持是玩不转DITA的，而使用商业解决方案的话，成本是一个重要的考量因素，小公司不一定愿意在这方面花钱。这本书的“进阶篇”写得非常好，该篇详细介绍了高质量技术文档需要满足的三要素（实用性、可读性和舒适性），运用大量的实例来帮助读者提升写作质量。例如，为了说明“从方便检索的角度来组织主题”，更高效地对信息进行分类，作者举了这么一个例子：（修改前）基本查询命令查询功能介绍查询报告的类型立即查询其他高级查询命令查询示例定制化报告的功能数据转换功能（修改后）功能介绍查询功能定制化报告的功能数据转换功能查询操作查询报告的类型立即查询查询示例命令参考查询命令转换命令对比一下，修改前的案例，写作者将内容界定为“基础”和“其他”两大分类，虽然这么分也没什么错，但是给人感觉有点牵强，逻辑上不够清晰明确。修改后的案例，对目录按照内容区别进行了分类，条理更清晰，读者更容易定位具体的内容。用英文进行技术文档写作时，由于国人普遍接受过严谨的语法训练，因此大家都比较注意遣词用句。相比之下，由于中文是我们的母语，很多时候我们都是凭借语感来写作，没有过多留意中文语法方面的问题。最常见的问题就是，中文技术文档中的章节标题，容易出现不规范现象，如忘了用动宾结构等。这本书中也有相关的讲解，值得细细品味。在“实战篇”的用户手册写作指导中，作者用FileZilla Client来讲解，写得非常详细，对新手来说参考意义很大。总体来说，笔者对《科技文档写作实务》一书的评价还是较高的。刚入行的技术文档工程师可以从中学到不少东西，老手也可以看看，毕竟中兴作为大企业，总结出来的一些经验还是值得借鉴的。说完了好话，最后也提一下建议吧。1）建议单独出一本技术文档写作的书，因为研发文档和用户文档的差异还是挺大的，读者群也明显不一样；2）有关Style Guide的话题一笔带过，感觉有点欠缺；3）既然中兴用的是DITA方案，那直接亮明观点，讲解更多DITA的实际运用也未尝不可；4）部分业内专用词汇，建议注明国际通用的英文表达，以体现专业性。举个例子，在书中看到“同源开发”一词时，笔者愣了一下才反应过来，这个指的是Single Sourcing。 （本书评首发于 http://www.chinatechwriting.com/kejiwendangxiezuoshiwu-review/ ）
精彩短评 (总计2条)
-
稍微有点空 -
写得相当不错了