如何写作技术文档-总述

在技术传播介绍中我们介绍了技术传播相关的职位，虽然职位很多，但从目前看，技术传播最主要也是最基本的是交付面向最终客户的文档资料。

在交付过程中需要做的事情往往包括：

1. 收集需求

• 设计信息架构
• 制定计划
• 制定模板和规范
• 开发资料
• 管理资料

这里有两个方面的内容：

• 写作技术
• 资料工程方法

文档工程方法

从工程方法的角度看，文档是跨部门相互协同的系统工程，他们的关系大致如下。

• 让最了解产品和技术的人员和部门提供高质量的原材料
• 文档也是产品，是信息产品，文档端到端环节都应有相应的流程与规范，各部门各司其职
• 文档开发人员负责信息设计、信息加工与写作、信息的组织与发布，并有责任向周边传递写作技能
• 研发发布给客户的文档，文档开发人员需要把关，保障整体信息体验一致

文档开发工程方法没有固定，需要根据实际项目具体定制，但大体上离不开上面几点。

抛开项目管理的内容，单纯的“写”大致可以分为四个阶段：

• 架构阶段：探索客户需求，追溯用户场景&分析任务场景&分析任务
• 设计阶段：梳理层次化结构，形成大纲
• 写作阶段：写作任务与操作，写作原理知识，写作案例，写作其他
• 评估阶段：体验三阶段

总体来讲，能做好上面四点的话，基本上文档质量就能达到可用或者说好用的程度。

后面我将具体介绍四个阶段的内容以及相关方法，一步步的认识如果写作出一本技术文档。

文档开发的层次模型

从下向上的看，文档开发层级越来越高，直至信息最终呈现：
1、基本的写作规范、文档的设计编辑和发布以及研发输入的文档是文档开发的基石
2、第二层是基于逻辑的文档写作，主要是下面几点
- 结构化、层次化的思维与表达
- 清晰性：易于理解和记忆
- 正确性：头脑中形成的虚拟产品与真实产品一致
3、第三层是基于客户思维的写作，关注用户目标，以及用户为达成目标而执行的任务和操作
- 可用性思维：范围/背景>用户角色>叙述场景>建立用户工作流
- 可用性写作：客户目标>解决方案>配置逻辑>任务和操作>案例
4、第四层是信息分类，内容类型的描述和内容要素，主要为作者服务
- 每个主题属于一个Topic，完成一个目的，描述特定内容元素
- 重用
5、第五层是信息呈现，关注内容的最佳表现形式和推送，需要解决下面的问题
- 赏析悦目
- 易于搜索
- 交付