如何写作技术文档-总述

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

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

  1. 收集需求
  • 设计信息架构
  • 制定计划
  • 制定模板和规范
  • 开发资料
  • 管理资料

这里有两个方面的内容:

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

文档工程方法

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

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

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

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

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

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

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

文档开发的层次模型

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

推荐阅读更多精彩内容