如何写作技术文档-总述

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

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

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

这里有两个方面的内容:

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

文档工程方法

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

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

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

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

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

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

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

文档开发的层次模型

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

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 204,921评论 6 478
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 87,635评论 2 381
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 151,393评论 0 338
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 54,836评论 1 277
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 63,833评论 5 368
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 48,685评论 1 281
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 38,043评论 3 399
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 36,694评论 0 258
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 42,671评论 1 300
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,670评论 2 321
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,779评论 1 332
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 33,424评论 4 321
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 39,027评论 3 307
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,984评论 0 19
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,214评论 1 260
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 45,108评论 2 351
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 42,517评论 2 343

推荐阅读更多精彩内容