如何当个优秀的文档工程师？从 TC China 看技术文档工程师的自我修养

2023-03-31
浙江
本文字数：4662 字
阅读完需：约 15 分钟

本文系 NebulaGraph Community Academic 技术文档工程师 Abby 的参会观感，讲述了她在中国技术传播大会分享的收获以及感悟。

据说，技术内容领域、传播领域的专家和决策者们会在中国技术传播大会「tcworld China 2022」大会上分享心得。作为一名技术文档工程师，本着了解相关行业的发展趋势和提升自我为 NebulaGraph 社区创造更大价值的心态，参加了此次大会。第一次参加 tcworld China 技术传播大会，干货挺多，记录一下参会的收获和感受。

tc，技术内容，全称 technical content。既然是技术内容，那么技术内容是如何进行传播呢？

初看，会觉得技术传播和作为内容生产者的技术文档工程师或资料开发没有半毛钱关系。然而，是本人坐井观天了：全场听下来，许多课程主题涉及“从内容到营销”，当中不乏营销常出现的词汇——“故事传播”、“内容运营”、“视频传播”等等。即便是针对产品编写的"说明书"，也是需要考虑用户和其使用场景，这正是传播的逻辑。除了涉及“从内容到营销”主题，大会还分享了文档呈现及编辑器的演进和发展、文档工程师的价值等主题内容。

下面由我带大家回顾一下这次的技术传播学习之旅。

课程主题

听了技术传播大会的大部分课程，从「技术文档工程师的价值」到「如何传播运营技术内容中的各个环节」，本次大会都有对应的课程主题。大会课程主题可以形成一条链路：

注：TW，全称 Technical Writer，即技术文档工程师。

干货及思考

大会中对技术文档工程师的价值、文档内容编辑方式、呈现方式、运营方式的现状及发展趋势做了相应的分享。在这过程中，我也收获了一些新知识和有了自己的一些思考。

技术文档工程师的价值

首先，技术文档工程师是什么？引用百科中的一句话———“文档工程师，是指协同开发人员，收集资料，安排开发计划，编写企业项目开发所需的各类文档，同时保证文档的质量、安全等的技术人员，他们肩负着软件开发过程中信息处理与整合的重要职责。面对“文档”，他们需要完成包括安排开发计划、制定各类模板、跟踪编写进度以及编辑管理等在内的一系列工作，实现文档处理的“一条龙”服务。”

有人可能会说技术文档工程师就是给产品 / 项目编写文档的人员。这也就延伸出来一个现象：文档工程师的价值经常被挑战。有些老板甚至文档工程师自身会想，为什么企业不训练一个开发工程师来直接写技术文档呢？这样他对技术的理解还会更强。为什么还要设立这样的专职的岗位？

首先，这样的技术人员不太好找，具有技术文档编写能力的技术人大多都希望深耕自身的技术领域，而不愿意去写这些对“硬”技能能力提升不多的内容。毕竟，相较于文档更轻量的注释已经够让技术人头疼了。另外，就是专业的技术文档所呈现的内容无论是可读性，还是对产品的理解会比其他人写出来的更好、更贴近用户。目前，全球许多大企业都在大量聘用技术文档工程师，像海康、阿里都有几十人的技术文档团队，人力不足的时候还需要外包。企业愿意付出这样的成本去招聘相关人才，就证明了技术文档工程师有其独特的价值存在。

这也是为什么会专门存在这样的部门。因为，之前未设立技术文档部门时，其他人来写这块内容呈现的效果非常差、用户体验不佳。因此，很多企业才会存在技术文档这个部门，来帮助企业解决人员分工问题。假如一个企业里的技术人员既要写东西，还要去做技术或是去设计产品，就会出现超级节点。那么，分工的出现就解决这一痛点：专门的人才从事文档编写，专门的人才来搞技术，这样才能把分工内的东西做精做好。

如何提升文档团队的影响力

作为文档工程师，首先需要肯定和提升自己的认知维度，提升文档团队的影响力，具体怎么做？参考下列方式：

打破角色固化的认知，拒绝做边缘人。文档角色只能输出内容吗？不止是这样，文档可以发现 bug、了解和分析用户需求、给产品设计提需求及意见。
有意识地训练产品思维，保持对产品的好奇心和敏感度。
多接触真实的用户，去现场给用户培训，更好地了解用户实际使用产品中遇到的问题，减轻用户的学习成本。像是 NebulaGraph 这类开源产品，会经常查看社区用户常提到的问题，并将该问题和解决方案写在文档中。
学习用户体验法则、尼尔森的十大可用性原则，利用「用户旅程地图」发掘机会点。
从用户痛点出发提出问题，并给出初步解决方案，和产品交互进行沟通并推动提升用户体验，从而提升文档团队的影响力。

招聘和培养英文技术文档

如果技术内容传播还泛指国际上的传播，那么英文技术文档对于产品的国际化具有关键作用。tcworld China 2022 分享中提到，在进行英文技术写作人员招聘过程中，常常遇到三个问题英文能力不足、技术能力不足、写作能力不足。

当急需人才、短期内又招不到人的情况下，企业可以转变思维，对英文技术翻译人员进行培训。在语言和写作方面，英文技术翻译人员上手会相对较快。剩下的就是对其技术方面的专门培训。像是英文技术文档这种人群的招聘前提也是需要 ta 们具有很强的学习意愿和能力。

文档未来

听完全场，我更喜欢 RWS 呼延韶文老师分享的《文档未来》课程，他从内容的创作方式和内容的应用端两个方面分享了文档的发展趋势。

内容创作方式

文档的创造方式，已经从最初的纸质版转为电子版（Word / PDF）的方式交付。文档正从纸质转变为电子再转变成数字化。文档数字化，指文档内容模块化、结构化、文档生产流程的云化、文档和用户的可交互性。《文档未来》提到 Forrester 预测文档下一个十年，新型基于云端、数据驱动、结构化的文档创作方式将成为主流。基于结构化、模块化主题内容，还可做到文档内容的自动组合、更新自动推送等等。文档内容呈现的发展的最后阶段是交互性内容，用户可以和内容进行交互（多以 HTML + CSS 实现）。与技术的互动，从文本到交互界面，是由产品设计引发的潜意识过程所引导的。技术传播者越是了解这种心理过程，越能创造出互动强的文档。

不仅仅《文档未来》提到了文档内容的模块化、结构化，其他的课程《让技术文档智能化交付+多场景呈现》、《如何构建知识百科并营销，共建产业生态》也都提到了文档内容的模块化和结构化。结构化的主题内容可以一源多用，并多格式发布。相对传统的编辑方式，结构化能起到降本增效的作用。这种结构化、模块化的内容呈现是基于 XML 的体系结构，比较火热且流行的标准是 DITA 标准。目前，NebulaGraph 技术文档团队正在使用开源的文档编辑软件 MkDocs Material（参考延伸阅读），满足目前的内容复用需求。随着文档内容量不断增多，后续可以考虑使用结构化、模块化的编辑软件创作文档内容。

内容应用端

文档内容发布后，用户需要在门户网站浏览文档内容。那么，如何呈现内容或者说如何组合内容以提升用户体验呢？这个部分的内容和后面《开源网站信息架构的攻守之道》提到的信息架构有相似之处。在应用端（文档网站）可以做的用来提升用户体验的事情：

语义化的搜索能力，搜索引擎可以根据用户的使用场景，搜索词语的意思检索到目标内容。
知识模块化，基于 XML 体系的内容发布。
智能内容，智能机器人可以推送用户搜索的问题。
考虑用户常搜索的关键字，考虑 SEO 创作内容。

信息架构 IA

在参加这次技术传播大会之前，我只是知道 IA（Information Architecture）这个词比较火，但不懂什么是真正的信息架构。信息架构是什么？用途是啥？参加了大会后，大概知道了 IA 的概念，但是还是有点模糊具体是 IA 是做什么？于是在网上找到了一篇浅显易懂的《如何进行信息架构设计？》。下文仅列举相关概念。