如何写出优秀的技术文档?

无人久伴 提交于 2021-01-02 06:55:55

大家好,我是小枣君。


鲜枣课堂自从2017年5月开始正式创立,迄今已有3年多的时间。这一期间,我们的内容一直都坚持以技术类科普文章为主,输出了大约400多篇原创。其中绝大部分,都是我写的。


我的想法比较简单,就是希望能够输出通俗易懂的技术科普文章,让技术不再枯燥,帮助更多人(尤其是即将进入行业的年轻人)了解通信,了解5G、物联网、云计算和大数据这样的ICT领域前沿科技知识。


非常庆幸的是,鲜枣课堂的内容受到了大家的欢迎,得到了宝贵的认可,也积累了越来越大的影响力。我们现在已经逐渐成为行业里排名前列的技术类内容原创自媒体。


其实,我之所以会选择技术文章写作这条路,和我的个人经历是分不开的。


我曾经在某设备商做了四年的技术支持(其中三年海外),积累了丰富的通信产品技术知识和实践经验。然后,又做了三年的文档经理,积累了大量的文档写作、文档体系建设、文档质量管理方面的经验。最后,又做了四五年的培训经理,学习如何进行高效的内容表达、如何针对内外部客户进行知识传递。


多元化的职场经历,为我创办鲜枣课堂贡献了知识背景和能力基础。


尤其是技术文档写作这一块,我从刚入职就养成了经验随手总结、技术定期积累的日常写作习惯,并保持至今,可以说是受益匪浅。


文档,不管是对于员工个人,还是对于企业,都有非常重要的意义。对于技术类公司来说,技术文档的重要性更是不言而喻。它的价值,完全可以等同于产品本身。或者说,技术文档就是产品的一个重要组成部分。


很多人认为文档是产品的附属品,是例行公事的印刷品,这显然是不对的。


文档的根本性质,是贯穿产品生命周期的沉淀积累输出物,是信息传递的重要工具和载体。不同阶段的文档,有不同的作用。不同的岗位,有不同的文档体系。


在产品设计和研发阶段,有产品设计指导书、产品功能需求说明书等。在产品工程交付阶段,有版本发布说明、技术指导书、升级/割接/扩容指导书等。


产品文档体系的范例


文档还分为内部文档和外部文档。内部文档服务于内部用户,外部文档服务于客户、合作方等外部用户。内外部文档密级不同,内容会有所删减,表述方式和侧重点也会有所不同。


文档用于指导实际工作。文档质量的好坏,会影响信息传递的准确性和效率,进而影响工作的完成、项目的交付。


例如,产品开通文档太烂,客户看不懂,合作方员工看不懂,甚至自己的工程师也看不懂,就无法依照文档成功完成设备开通或升级割接。文档如果出现错误,甚至可能造成严重的事故。


现在市场竞争越来越激烈。有时候,虽然产品本身做得很好,价格也很有优势,但是文档太烂,一样会被客户鄙视,进而拉低了产品的整体竞争力。有损公司品牌形象。


那么,决定产品文档质量的基本要素是什么呢?


有人说,是作者的写作水平。也有人说,是是否有充足的时间。


其实都不对,基本要素只有一个,那就是钱。


文档写作是一个需要投入大量资源的工作。


首先,需要建立一个完善的文档管理体系,包括文档架构体系,文档职责归属,文档立项、开发、评审、发布、归档流程以及对应平台等。


其次,需要安排大量的专任或兼任岗位跟进相关流程管理,占用工时。


再有,文档和产品开发一样,是一个滚动性流程,需要不断更新迭代。所以,资源投入也是持续性的。


早期的时候,国内很多企业利用人力成本优势,发起人海战术,将资源集中投入到产品研发上,靠价格优势和版本速度(需求响应速度)抢占市场。


开发工程师忙着写代码,做版本,哪有时间去写文档?基本上都是拿产品设计指导书改一改,截截图,就扔给了售后,甚至扔给了客户。


内部用户(售后)骂娘,领导其实心里有数,毕竟资源有限,只能牺牲文档保版本,对内部反馈进行弹压。而外部客户的意见,是无法进行弹压的。


对于一些低端客户来说,比较关注的是价格。极端的成本优势,可以让客户忽视文档。但是,对于高端用户来说,他们对文档的要求和对产品的要求是一致的。没有优秀齐套的文档,一样不给中标。


于是,倒逼设备商投入资源补齐短板,组织人力进行文档专项开发。结果发现,其实并不是写不出好文档,而是之前没有舍得投入资源。


然而,一旦项目应付过去,资源又会撤走,好不容易建立起来的文档质量,又再次垮塌,如此恶性循环。


所以说,对于企业,想要把文档满意度搞好,树立有利于产品品牌的文档品牌形象,关键在于领导愿不愿意投钱。有钱就有人有资源,这是搞好文档的基本前提。


随着市场的规范和成熟,加上竞争日趋激烈,文档的重要性不断提升,越来越多的企业负责人开始意识到这个问题,不断加大对文档的资源投入。


战略层面的重视是基础,战术层面的执行是关键。


前面说的文档管理体系,是有一整套方法论的。大到文档体系的架构(到底需要多少篇文档,分别由谁来负责,写给谁看),小到文档内容的编写,都有相应的理论和技巧。这些不是靠人海战术就可以完美完成的。


限于篇幅,我就不详细介绍文档管理体系了。我重点说说单篇文档的写作技巧。


想要写好一篇文档,首先第一个问题,就是你要搞清楚这篇文档的定位——它是一篇什么性质的文档?写作目的是什么?它的使用者是谁?


文档的定位,直接决定了整篇文档的基调。


例如我经常写的零基础入门,定位就是对相关内容背景知识毫无了解的读者。然而,又不是小学生那种层次,而是至少已经完成了基础教育,处于大一及以上学历水平的读者,有基本的物理学和数学常识,也有对自然现场的基本认知,还有正常人的逻辑思维能力。


如果你写技术文档,首先要搞明白,文档使用者是内部客户还是外部客户,是有经验的客户,还是零基础的客户,是已经阅读过前置文档的客户,还是第一次看这套文档的客户。


明确了对象之后,要切记,在写作整篇文档的过程中,你都要随时切换自身角色。一定要站在读者的角度,琢磨文档内容是不是能看得懂。


如果没有把握,那么,就找个和目标读者处于同等水平的体验用户,让他试读,提供反馈意见。


大部分技术文档的作者不是作家,甚至不是文科生,而是技术工程师。这类人在文字表达技巧上通常比较欠缺,但是有一个显著优势,那就是逻辑思维能力强。对于写作来说,这一点非常重要。尤其是技术文档的写作,必须有很强的逻辑思维能力。


文档的总体结构,必须要有逻辑连贯的章节顺序。文档的语句,也必须有逻辑严谨的表述方式。过于跳跃的思维,不适合应用于技术类文档。文科生过于感性的文字,也不适合技术类文档。


技术工程师最常犯的毛病,就是自以为是:“这么简单,你怎么都不懂?”“这是基础啊,是个人都懂!”然后就偷工减料,言简意赅,跳过了大量的细节,忽视了可能出现的不同情况,让文档使用者不知所措。甚至有的作者,喜欢玩“玄学”,觉得越写得高深,就越显得自己很懂,简直可笑。


规范的技术文档,通常会遵循SOP的原则。所谓SOP,就是 Standard Operating Procedure,标准作业程序。


下面这段内容,是一个SOP文档写作的范例:



大家会看到,前置信息非常充分,该介绍的背景,都会介绍到位。


具体的操作步骤,虽然简短,但内容十分清晰,分为几个步骤,每一个步骤敲什么命令、有什么目的,都会告诉你。


在最后,还会有验证结果环节(本例的验证结果部分相对简略,实际上还应该包括通过命令,查看结果,以此进行明确验证)。


上面这种SOP的文档写作方式,和我们从小接受过的传统写作是完全不同的,


以前我们常说,中式菜谱喜欢用“盐少许、酱油少许、大火煎炸片刻”这种定量非常模糊的表达方式,其实确实和我们的写作习惯有一定关系。对于技术文档来说,我们这方面的偏重性培养和训练确实做得不够。真正的写作,不是刻意追求辞藻的华丽,而是意思和情境的准确表达。


要想写好技术文档,还有一个重要技巧,那就是多用图表。


所谓“字不如表、表不如图”。技术是很抽象的东西,也是理解起来很有难度的东西。想要靠纯文字进行内容转述,是很困难的。所以,应该更多地借助表格和图片,甚至gif动图,帮助读者理解。


说白了,这个就是考验作者的责任心。如果写作者不能站在读者的角度,不能以读者满意度为出发点,那么,就不会愿意多此一举去画图。画图是很复杂的工作,有时候我写文章,一幅图都要画一天,很不容易。


技术文档的写作,不仅对企业来说非常重要,对于个人来说,也是受益匪浅的。


养成并坚持写作的习惯,有利于培养逻辑思维能力,也有利于个人知识沉淀积累。个人可以开技术blog或公众号,发表并分享自己的经验心得,会很有成就感,日积月累的话,甚至可能形成个人品牌和影响力,有利于自己的职业生涯发展。

虽然现在视频化的趋势明显,但是我个人认为,文档是无法被视频取代的。目前的技术,视频无法进行快速内容检索,无法进行快速更新和修改,无法进行快速传递,文件体积较大,这些都决定了文档的不可替代性。


视频的优势,更多在于内容形象而生动的展示,可以让用户有更感性的认识,更深刻的记忆,适合培训,不适合工作查阅,不适合归档。



好啦,以上就是小枣君关于技术文档写作的分享,希望对大家有所帮助。顺便打个小广告,大家如果有自己觉得还不错的技术文档输出,也欢迎投稿给鲜枣课堂,稿酬丰厚!


最后,感谢大家的耐心阅读,我们下期再见啦!


—— The End ——




本文分享自微信公众号 - 鲜枣课堂(xzclasscom)。
如有侵权,请联系 support@oschina.cn 删除。
本文参与“OSC源创计划”,欢迎正在阅读的你也加入,一起分享。

标签
易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!