配图来源于全景网
作为一名初入行的技术写作者，我们首先要清楚，我们的首要任务肯定是，努力做好我们最本职的工作，也就是，写出漂亮的技术文档。那么，初入行者，如何写好技术文档呢？我们需要具备哪些软硬技能呢？在这篇文章中，我主要想针对这些问题跟大家分享一下我的个人经验。
写好技术文档必备硬技能
硬技能1：产品理解
我在上一篇文章《技术写作职业入门记》中提到了产品理解在技术写作中的重要性。那么，我们可以通过哪些方法和途径来全面深入理解产品呢？对于这个问题，我的经验可以归纳为三个字。
学：学习的资料包括但不限于产品需求文档、设计文档、竞品相关资料、此产品上一代产品相关资料。研读这些资料的过程中，我们基本了解这款产品的功能轮廓。对于不了解的专业词汇、功能点可以继续查资料进一步学习，将无法通过自学解决的问题记录下来。
问：关于产品，我们询问的对象包括但不限于研发工程师、项目经理、产品应用工程师和市场相关的同事。如果有条件，也可以包括用户。我们可以把这个环节类比为记者的采访。不同的采访对象，我们提出的问题应该有所不同。比如：研发工程师，问技术实现的细节；项目经理，问产品的战略布局；产品应用工程师，问某些功能的具体应用场景、优势如何凸显、劣势如何回避等。
用：如果说第一个“学”字是纸上谈兵，那么这个“用”字就是上阵实战。你们家的产品你一定要会用。如果你都不知道怎么用，怎么告诉你的用户怎么用？如果是硬件产品，那么就要去接线、去调试；如果是软件产品，就去操作。你文档里写什么操作的指导，你就要去做相应的操作流程。只有这样，才有可能写出具有指导意义的文档。
硬技能2：写作能力
无需多言，写作能力在技术写作中同样毋庸置疑的重要。我相信，既然选择了这个职业，我们的文字表达能力自然不会太差。值得关注的是，当写作对象被限定为技术文档时，对写作能力的要求主要体现在哪些方面呢？此处，归纳出两点我的个人经验仅供参考。
注意逻辑主线：技术文档不是散文诗歌，逻辑主线非常重要。大到整篇文档的章节安排、小到一个操作的执行步骤，我们一定要注意逻辑的清晰。常用的逻辑主线可以归纳为如下四种类型。
-
顺序逻辑：凡涉及操作步骤的内容均使用此类逻辑结构。
-
树状逻辑：常见于文档架构的确定。
-
关联逻辑：如：“实现某种功能的N种操作方法”这类Topic的写作。
-
数据逻辑：常见于技术指标，产品规格，数据曲线等内容的表达。
语言简明扼要：技术文档的语言应尽量简要明了，自然朴素不求粉饰，把你要表达的意思直白的传达出来便可。避免使用可能产生歧义的表达方式，避免使用复杂的难以理解的表达方式，尽量使用短句子，便于用户理解，降低翻译难度和错译的几率。
硬技能3：沟通能力
技术写作是一个综合性很强的职位。在一个企业里，技术写作者几乎需要和各个岗位的同事打交道。研发部的软硬件工程师、结构工程师、工业设计师、测试工程师、项目经理；市场部的产品应用工程师，企业视觉设计师、网站管理人员；采购部负责纸质文档采购的工程师；生产部负责电子版文档刻盘管理、包装发货的负责人……因此，高效的沟通可以节约大量的时间，使工作效率事半功倍。这方面，我的经验可以归纳为以下几点。
选择最高效的沟通方式：
-
对时效性要求高的沟通，当面沟通或者打电话是比较好的选择；
-
问研发工程师比较复杂的问题时，建议采用邮件问+当面听答案的方式进行。首先，写作属于我们的强项，写邮件的时候可以帮助我们梳理清楚问题，而且邮件可以图文并茂的提问题。研发工程师回答问题的时候，通常需要配合现场演示、手绘草图等方式辅助解释，带上我们的耳朵和脑袋，仔细听，认真记，随时问，回头整理出答案，发给对方确认一下。
使用对方熟悉的表达方式：这一点要靠一段时间的揣摩观察和积累。比如：我之前所在的公司，每个项目都有一个英文单词代号，研发工程师通常只知道代号不太了解型号，其他部门同事多数只知道型号不清楚代号。我们在跟不同的同事沟通时，知道这些信息，选择对方熟悉的表达方式，有助于信息的传达。
长时间的沟通提前预约：当今的企业多数是“一个萝卜一个坑”或者“一个萝卜好几个坑”，大家都处于工作量高饱和的状态，较长时间的沟通最好提前预约（我个人一般以20分钟为分界点，预计为20分钟以上的沟通会提前预约），不仅有利于我们有充足的时间获取所需答案，也有利于我们个人职业素养的建立。
不要孤立自己：如果你在一个技术写作小团队中工作，那么恭喜你，团队归属感你已经拥有了。不那么孤独的你，请与你的战友们团结一心，相互帮助，相互批评，共同进步。即使你是单兵作战，也千万别孤立自己。这个时候，往大一点的圈子去看，研发部或者市场部，那就是你的团队。混在研发的队伍里面，这种情况更容易和研发打成一片，便于接收第一手的项目信息。
硬技能4：工具使用
图文编辑工具是技术文档呈现的最后一道硬技能门槛。一些大型企业有专门的插图工程师和排版工程师，但是绝大多数的企业，技术写作者自身都是多面手。
因个人经历有限，我所接触到的文档写作工具主要是word和Acrobat，曾经还使用过Frontpage编译chm格式在线帮助文档；插图处理工具有matlab、visio、ps、AI、CorelDRAW等。仅就我工作所需的几款工具来说，有如下几点经验可分享给大家。
-
如果你们也主要使用word和visio，请充分利用起样式和模板功能，可以提高效率。
-
关于我用过的工具的学习，我建议在实践过程中进行功利性的学习，即有非常明确目的的学习。边学边用，边用边学。
-
学习图文工具，我认为网络资源基本够用，我至今没买过这类的书籍。
写好技术文档必备软技能
软技能1：求知欲和学习能力
学习学习再学习，重要的事情说三遍。
每接一个新项目，都有一片海等待我们去探险；每隔一阵子，就要怀疑一下，我们的写作工具和开发流程是否依然适合当前的情况……如果不想继续学习了，这份工作你将做的举步维艰。这是我从业多年之后的切身体会。
软技能2：资料获取能力
关于这一点，我想说，练好我们的网感很重要。所谓“资料获取能力”，除了从你们企业项目管理处获取的资料之外，更多的是我们从网上找我们需要的资料。问一下竞品是哪个品牌的哪款产品，去对方网站上下一整套资料；一个知识点搞不清楚，各种文库找论文，找资料，上可追溯到知识点的起源，下可了解到最新的发展趋势。
软技能3：基本的审美能力
技术文档就是我们生产的产品，每一字，每一段，每一张图，都是这个产品的零件或者说是界面。我们既是生产者，也是设计师。我们需要具备一点基本的审美能力，让我们生产设计出来的产品简洁大方，起码让人愿意看。
软技能4：拥抱变化的心态
我们跟一个项目，刚按着A方案写完一套文档，产品迭代为B方案；刚按着B方案改完文档，产品迭代为C方案；刚按着C方案改完文档，产品变更为A方案……这种情况，请不要焦虑，也不要骂街，因为“变化才是真正的常态”，因为“唯变不变”，请拥抱变化，世界将无比精彩。
以上分享了我的个人经验，鉴于我的经历和水平所限，文中难免存在疏漏，欢迎各位同行不吝给予纠正和补充。未完待续……敬请期待下一篇文章《初入行的技术写作者还需要了解的几件事》。
网友评论