四川网站建设外包业务,网络优化分为,手机之家中关村在线,个人网站备案 法律说明我作为从一名懵懂的实习生转变为工程师的工作经历中#xff0c;伴随着技术经验的成长#xff0c;也逐渐意识到了编写文档是知识和经验传递给其他人的最有效方式。通过文档#xff0c;可以分享我的技术知识和最佳实践#xff0c;使其他人更好地理解我的工作。在这里#xf… 我作为从一名懵懂的实习生转变为工程师的工作经历中伴随着技术经验的成长也逐渐意识到了编写文档是知识和经验传递给其他人的最有效方式。通过文档可以分享我的技术知识和最佳实践使其他人更好地理解我的工作。在这里给大家浅谈一下作为技术研发如何写好技术文档 目录 为什么了解读者什么是了解读者常见的信息差来源——术语常见的信息差来源——相似物常见的信息差来源——新事物 如何了解读者总结 为什么了解读者
在日常写文档过程中大部分技术同学不会花太多时间去了解“读者”。然而由于缺乏对读者对了解大部分的技术文档的“可用性”是很差的。
“可用性良好”的文档主要是指读者能看懂文档内容并且读者能借助文档顺利达到他的目的。比如完成一个任务或者了解一个概念。 反之“可用性不好”的文档即使读者能看懂文档可能也没有办法帮助他解决问题。举个栗子
写给小白的技术文档充斥着艰深的术语又没有任何术语解释。写给运维工程师的文档不重点介绍运维操作却花大篇幅去介绍技术原理。
什么是了解读者 明确读者身份: 文档最终的读者是小白用户or资深用户或者是运维人员or开发人员? 确立文档的受众是第一步。 明确读者阅读目的:该文档是为了让读者了解一个概念、完成一个步骤,还是查阅一个参数解释。先确立了文档的目标才能保证写文档时的大方向不会走错 举个例子: 某绘图软件的用户手册 文件菜单按钮:用于创建新文件,打开文件,重命名文件等裁剪按钮:用于裁剪出图片中选中的区域… 该文档作者很详细的描述了界面上各个控件的功能但是该文档与其说是“用户手册”不如说是“功能清单”。用户很难找到他所需要的内容。 基于读者视角该文档应该介绍这个软件可以解决的具体问题。绘图软件的目标读者一般都是设计人员那么他们的阅读目的就是完成绘图的各个步骤。修改后的版本应该使读者快速定位到有用的内容 如何捕捉图片如何选择背景如何绘制椭圆形和圆形… 明确读者所需信息:根据读者的认知能力提供所需信息。比如目标用户是小白则不能写的过于艰深。 针对不同的读者群体应该提供差异化的内容不同认知水平的读者所拥有的信息水平也是不同的即“信息差”。对于文档写作者和读者的信息差写文档时应该尽量去弥合信息差将读者的认知水平拉齐到和作者一样的高度。 The curse of knowledge(知识诅咒/知识陷阱)你越是深入到了解一样东西则你越难体会/不了解他人的状态。 很多时候我们难以意识到“信息差”的存在。在写文档时尤其注意需要补充这些读者不知道却又必须知道的关键信息否则容易导致文档的不可用。 常见的信息差来源——术语 我们在使用术语时一定要注意术语的规范性。例如以下文档 大池子肉鸡CPU打到60% 此类文档就是把一些“行业黑话”当成术语写在文档里面。这是应该尽力避免的。 其次同一个术语应该尽量用同一个意思来表达比如“接口”有的人喜欢叫“API”有的人喜欢叫“方法”。那么在同一篇文档里应该统一用接口或者统一用API不能换来换去避免读者造成不必要的困惑。 最后应该在文档中提供及时的术语解释。例如用超链接引用注释块等技巧。可参考以下文档 允许您创建消息组以适应不同的业务场景在不同的国家或地区可以使用签名和可用的模板 签名指在文本消息正文之前的xxx用于识别公司业务模板… 常见的信息差来源——相似物 当一个产品提供了两个相似的功能文档需要帮助读者辨析方便其做出选择。例如通过表格对比的方式列出两个产品的不同点 常见的信息差来源——新事物 作为技术研发我们不管是在交代步骤还是在解释概念时所有新出现的事物都需要充分解释其来源。 下例文档详细交代了如何获取AppID、AppName和region。这些信息一旦缺失,就可能影响客户满意度、并带来额外的客户支持成本。
如何了解读者
了解读者的阅读目的以及所需信息也是至关重要的。 当我们有足够的时间和精力可以尝试主动走近读者
邀请同事评审 把身边同学作为目标受众,获得反馈意见。最后再对文档进行反复修改反复打磨。读者访谈 与读者约一次访谈,了解他们对文档的期待、建议和意见。文档支持群 建立文档支持群,收集第一手的文档问题。这是一个长期、可靠、优质的渠道,通过该途径可以收集到许多鲜活的、高价值的文档反馈。
当然如果没有条件则可以选择第二种路径即在动笔写文档之前做一次头脑风暴想象出作为读者的阅读历程
读者从哪里来? 写此文档背景是什么?读者遇到了什么困难,要完成什么任务?读者最开始是什么状态?他们此时在做什么,手边有哪些资源?读者在哪儿? 想象读者此时所处状态?比如,此时在哪个文件夹下?读者怎么确认他们处于文档里说的这个状态?比如执行某个命令,应该返回什么结果?读者到哪里去? 为什么要告诉读者这些信息?对他们有什么用?读者下一步要做什么?
总结
