如何写出优秀的技术文档?
大家好,我是小枣君。
鲜枣课堂自从2017年5月开始正式创立,迄今已有3年多的时间。这一期间,我们的内容一直都坚持以技术类科普文章为主,输出了大约400多篇原创。其中绝大部分,都是我写的。
我的想法比较简单,就是希望能够输出通俗易懂的技术科普文章,让技术不再枯燥,帮助更多人(尤其是即将进入行业的年轻人)了解通信,了解5G、物联网、云计算和大数据这样的ICT领域前沿科技知识。
非常庆幸的是,鲜枣课堂的内容受到了大家的欢迎,得到了宝贵的认可,也积累了越来越大的影响力。我们现在已经逐渐成为行业里排名前列的技术类内容原创自媒体。
其实,我之所以会选择技术文章写作这条路,和我的个人经历是分不开的。
我曾经在某设备商做了四年的技术支持(其中三年海外),积累了丰富的通信产品技术知识和实践经验。然后,又做了三年的文档经理,积累了大量的文档写作、文档体系建设、文档质量管理方面的经验。最后,又做了四五年的培训经理,学习如何进行高效的内容表达、如何针对内外部客户进行知识传递。
多元化的职场经历,为我创办鲜枣课堂贡献了知识背景和能力基础。
尤其是技术文档写作这一块,我从刚入职就养成了经验随手总结、技术定期积累的日常写作习惯,并保持至今,可以说是受益匪浅。
文档,不管是对于员工个人,还是对于企业,都有非常重要的意义。对于技术类公司来说,技术文档的重要性更是不言而喻。它的价值,完全可以等同于产品本身。或者说,技术文档就是产品的一个重要组成部分。
很多人认为文档是产品的附属品,是例行公事的印刷品,这显然是不对的。
文档的根本性质,是贯穿产品生命周期的沉淀积累输出物,是信息传递的重要工具和载体。不同阶段的文档,有不同的作用。不同的岗位,有不同的文档体系。
在产品设计和研发阶段,有产品设计指导书、产品功能需求说明书等。在产品工程交付阶段,有版本发布说明、技术指导书、升级/割接/扩容指导书等。
产品文档体系的范例
文档还分为内部文档和外部文档。内部文档服务于内部用户,外部文档服务于客户、合作方等外部用户。内外部文档密级不同,内容会有所删减,表述方式和侧重点也会有所不同。
文档用于指导实际工作。文档质量的好坏,会影响信息传递的准确性和效率,进而影响工作的完成、项目的交付。
例如,产品开通文档太烂,客户看不懂,合作方员工看不懂,甚至自己的工程师也看不懂,就无法依照文档成功完成设备开通或升级割接。文档如果出现错误,甚至可能造成严重的事故。
现在市场竞争越来越激烈。有时候,虽然产品本身做得很好,价格也很有优势,但是文档太烂,一样会被客户鄙视,进而拉低了产品的整体竞争力。有损公司品牌形象。
那么,决定产品文档质量的基本要素是什么呢?
有人说,是作者的写作水平。也有人说,是是否有充足的时间。
其实都不对,基本要素只有一个,那就是钱。
文档写作是一个需要投入大量资源的工作。
首先,需要建立一个完善的文档管理体系,包括文档架构体系,文档职责归属,文档立项、开发、评审、发布、归档流程以及对应平台等。
其次,需要安排大量的专任或兼任岗位跟进相关流程管理,占用工时。
再有,文档和产品开发一样,是一个滚动性流程,需要不断更新迭代。所以,资源投入也是持续性的。
早期的时候,国内很多企业利用人力成本优势,发起人海战术,将资源集中投入到产品研发上,靠价格优势和版本速度(需求响应速度)抢占市场。
开发工程师忙着写代码,做版本,哪有时间去写文档?基本上都是拿产品设计指导书改一改,截截图,就扔给了售后,甚至扔给了客户。
内部用户(售后)骂娘,领导其实心里有数,毕竟资源有限,只能牺牲文档保版本,对内部反馈进行弹压。而外部客户的意见,是无法进行弹压的。
对于一些低端客户来说,比较关注的是价格。极端的成本优势,可以让客户忽视文档。但是,对于高端用户来说,他们对文档的要求和对产品的要求是一致的。没有优秀齐套的文档,一样不给中标。
于是,倒逼设备商投入资源补齐短板,组织人力进行文档专项开发。结果发现,其实并不是写不出好文档,而是之前没有舍得投入资源。
然而,一旦项目应付过去,资源又会撤走,好不容易建立起来的文档质量,又再次垮塌,如此恶性循环。
所以说,对于企业,想要把文档满意度搞好,树立有利于产品品牌的文档品牌形象,关键在于领导愿不愿意投钱。有钱就有人有资源,这是搞好文档的基本前提。
随着市场的规范和成熟,加上竞争日趋激烈,文档的重要性不断提升,越来越多的企业负责人开始意识到这个问题,不断加大对文档的资源投入。
战略层面的重视是基础,战术层面的执行是关键。
前面说的文档管理体系,是有一整套方法论的。大到文档体系的架构(到底需要多少篇文档,分别由谁来负责,写给谁看),小到文档内容的编写,都有相应的理论和技巧。这些不是靠人海战术就可以完美完成的。
限于篇幅,我就不详细介绍文档管理体系了。我重点说说单篇文档的写作技巧。
想要写好一篇文档,首先第一个问题,就是你要搞清楚这篇文档的定位——它是一篇什么性质的文档?写作目的是什么?它的使用者是谁?
文档的定位,直接决定了整篇文档的基调。
例如我经常写的零基础入门,定位就是对相关内容背景知识毫无了解的读者。然而,又不是小学生那种层次,而是至少已经完成了基础教育,处于大一及以上学历水平的读者,有基本的物理学和数学常识,也有对自然现场的基本认知,还有正常人的逻辑思维能力。
如果你写技术文档,首先要搞明白,文档使用者是内部客户还是外部客户,是有经验的客户,还是零基础的客户,是已经阅读过前置文档的客户,还是第一次看这套文档的客户。
明确了对象之后,要切记,在写作整篇文档的过程中,你都要随时切换自身角色。一定要站在读者的角度,琢磨文档内容是不是能看得懂。
如果没有把握,那么,就找个和目标读者处于同等水平的体验用户,让他试读,提供反馈意见。
大部分技术文档的作者不是作家,甚至不是文科生,而是技术工程师。这类人在文字表达技巧上通常比较欠缺,但是有一个显著优势,那就是逻辑思维能力强。对于写作来说,这一点非常重要。尤其是技术文档的写作,必须有很强的逻辑思维能力。
文档的总体结构,必须要有逻辑连贯的章节顺序。文档的语句,也必须有逻辑严谨的表述方式。过于跳跃的思维,不适合应用于技术类文档。文科生过于感性的文字,也不适合技术类文档。
技术工程师最常犯的毛病,就是自以为是:“这么简单,你怎么都不懂?”“这是基础啊,是个人都懂!”然后就偷工减料,言简意赅,跳过了大量的细节,忽视了可能出现的不同情况,让文档使用者不知所措。甚至有的作者,喜欢玩“玄学”,觉得越写得高深,就越显得自己很懂,简直可笑。
规范的技术文档,通常会遵循SOP的原则。所谓SOP,就是 Standard Operating Procedure,标准作业程序。
下面这段内容,是一个SOP文档写作的范例:
大家会看到,前置信息非常充分,该介绍的背景,都会介绍到位。
具体的操作步骤,虽然简短,但内容十分清晰,分为几个步骤,每一个步骤敲什么命令、有什么目的,都会告诉你。
在最后,还会有验证结果环节(本例的验证结果部分相对简略,实际上还应该包括通过命令,查看结果,以此进行明确验证)。
上面这种SOP的文档写作方式,和我们从小接受过的传统写作是完全不同的,
以前我们常说,中式菜谱喜欢用“盐少许、酱油少许、大火煎炸片刻”这种定量非常模糊的表达方式,其实确实和我们的写作习惯有一定关系。对于技术文档来说,我们这方面的偏重性培养和训练确实做得不够。真正的写作,不是刻意追求辞藻的华丽,而是意思和情境的准确表达。
要想写好技术文档,还有一个重要技巧,那就是多用图表。
所谓“字不如表、表不如图”。技术是很抽象的东西,也是理解起来很有难度的东西。想要靠纯文字进行内容转述,是很困难的。所以,应该更多地借助表格和图片,甚至gif动图,帮助读者理解。
说白了,这个就是考验作者的责任心。如果写作者不能站在读者的角度,不能以读者满意度为出发点,那么,就不会愿意多此一举去画图。画图是很复杂的工作,有时候我写文章,一幅图都要画一天,很不容易。
技术文档的写作,不仅对企业来说非常重要,对于个人来说,也是受益匪浅的。
养成并坚持写作的习惯,有利于培养逻辑思维能力,也有利于个人知识沉淀积累。个人可以开技术blog或公众号,发表并分享自己的经验心得,会很有成就感,日积月累的话,甚至可能形成个人品牌和影响力,有利于自己的职业生涯发展。
虽然现在视频化的趋势明显,但是我个人认为,文档是无法被视频取代的。目前的技术,视频无法进行快速内容检索,无法进行快速更新和修改,无法进行快速传递,文件体积较大,这些都决定了文档的不可替代性。
视频的优势,更多在于内容形象而生动的展示,可以让用户有更感性的认识,更深刻的记忆,适合培训,不适合工作查阅,不适合归档。
好啦,以上就是小枣君关于技术文档写作的分享,希望对大家有所帮助。顺便打个小广告,大家如果有自己觉得还不错的技术文档输出,也欢迎投稿给鲜枣课堂,稿酬丰厚!
最后,感谢大家的耐心阅读,我们下期再见啦!
—— The End ——
如何写出优秀的技术文档?相关推荐
- 如何撰写出优秀的技术文档
技术文档分为两类,一类指开发中要用到的研发文档,一类是给客户看的客户文档,技术文档不仅仅适用于SaaS开发,他在各个领域都很常见,能够帮助记录团队/公司内部的一些资料,便于员工进行查询,通过正确的方法 ...
- 软文营销常用的方式有哪些?如何写出优秀的软文
如今硬广的效果越来越弱,软文营销逐渐吃香,相信不少人都对软文营销手法感兴趣,今天就给大家讲讲软文营销常用的方式有哪些. 一.故事式 顾名思义,就是通过讲述一个完整的故事,把产品信息隐蔽的贯穿在故事里, ...
- 写出漂亮的Markdown文档_v1.0.6
文章目录 文档撰写教程_v1.0.6 Markdown印象 什么是Markdown 编辑器选择 Typora Sublime 3 下载 实时预览 IntelliJ IDEA Editor.md CSD ...
- 优秀程序猿写技术文档的正确姿势
一.背景 写文档是程序猿进阶的一个必要步骤之一. 文档写的清楚,思路就更加清晰,也会让同事高看你一眼,多梳理业务也有很大帮助. 产品经理对需求文档基本是驾轻就熟信手拈来,但是大多数程序猿写技术文档却显 ...
- 如何写好技术文档 - 来自 Google 十多年的文档经验!
星标/置顶 公众号????,硬核文章第一时间送达! 本文大部分内容译自<Software Engineering at Google> 第10章节 Documentation.另外,该书电 ...
- 这谁写的技术文档?我想锤死他...
点击上方"朱小厮的博客",选择"设为星标" 后台回复"书",获取 后台回复"k8s",可领取k8s资料 很多技术人自己非 ...
- 如何写好技术文档——来自Google十多年的文档经验
文章目录 文档的重要性 为什么大多数人都不喜欢写文档? 如何产出高质量文档 像管理代码一样管理文档 明确你的读者是谁 清晰的分类 参考文档 设计文档 引导类文档 概念性文档 Landing pages ...
- 任天堂娱乐系统技术文档(屎王nes资料)
Nintendo Entertainment System Basic Information 任天堂娱乐系统技术文档 0.01 版 发布于 2002 年 8 月 14 日 作者:Necrosaro ...
- 不写技术文档是个什么梗
写文档在工作中很常见了,正规的公司都有文档,除非是很简单的东西. 文档用来给新人或不熟悉的人的看,出需求也要文档.只凭笔在本子上划几下不能让人懂. 凡是稍微复杂的东西一定用文档梳理流程,有的还有流程图 ...
最新文章
- OSChina 技术周刊第九期 —— 每周技术精选,值得一看!
- C++中“引用”的底层实现
- DCMTK:在图像数据库中注册图像文件的测试程序
- QT的QCategoryAxis类的使用
- 【Network】协议栈
- windows系统c 实现ftp服务器,windows系统c 实现ftp服务器
- LeetCode 708. 循环有序列表的插入
- 没数据时y轴不显示_Matplotlib数据可视化
- 【Delphi】从内存读取或解压压缩文件(RAR、ZIP、TAR、GZIP等)(二)
- java setmessage_Java Message.setTitle方法代码示例
- Exponent CMS 2.3.9 配置文件写入 Getshell分析
- 关于oneNote插件加载不显示的问题(NoteHighlight)
- love2d引擎开发资源合集
- C语言中%d,%o,%f,%e,%x的意义
- 图像模式识别 (五)
- matlab 椭圆方程拟合
- 根据脸部毛孔生长方向去护肤
- 深入理解空间金字塔池化(SPP,ASPP)
- 抓起整个网站离线浏览的软件Teleport Pro
- 中兴捧月比特派E题——反复横跳
热门文章
- 中毒了(QQ群搞笑聊天记录)
- 7-5 3824经典游戏分数 20 作者 李佳单位 重庆大学
- win10开机蓝屏_终级解决win10蓝屏代码WHEA_UNCORRECTABLE_ERROR没有之一 心语家园
- win7 android studio 升级HAXM后无法启动安卓模拟器
- CORBA 架构体系指南(通用对象请求代理体系架构)​
- adb 模拟键盘输入、点击屏幕、滑动、按键等操作
- 蛇哥开局两星机器人视频_腾讯内容开放平台
- c语言fgetc函数作用,C语言fputc()和fgetc()函数
- 微信小程序之本地网络服务器配置
- html怎么制作扇形,css3绘制画圆、扇形