【精华】技术文档工程师六大必杀技

Technical writing overview与Technical Writing Wikipedia对TW职业提供出了5点技能要求,总结得非常到位。另外,我也加上一条,凑成6点。 本文我结合20年技术写作经验,谈谈如何修炼这六点技能。

  • Facility with technology
    热爱技术,求知欲强,学习能力强。能深层次地探究与理解技术细节。

  • Ability to write clearly
    要达成这一点,需要做到以下两条:

    • Clear thinking becomes clear writing,只有对技术有了深入全面的学习与理解后,你才有可能把内容清楚地表达出来。你必须做到对所写内容有一个自成体系、融会贯通的认识。我的经验是:学习过后,尝试用自己的语言将它出来(注意是“讲”而不是“写”,因为“写”的时候你可以copy&paste, 并不能代表你融会贯通了)。的形式? 可以是:开展文档组内交流会、散步时讲给爱人听,也可以假想有观众在听,自话自说。在讲的过程中,你会发现理解上逻辑不连贯之处或有人会challenge你,又让你回过头对知识点掌握得不够清晰的地方再搞清楚。

    • 之后,用文字表达将搞清楚逻辑的内容清晰与简洁地表达出来。写作时,避免被动态,使用短句。技术越复杂难懂,语言越是要简单 (Please follow your style guide strictly)。

  • Talent in showing ideas graphically
    A picture is worth a thousand of words. 平时,多看多学习别家手册中绘图表达方式,开拓眼界。特别是现在用户文档越来越倾向于网上发布,色彩的应用于比传统打印文档丰富的多。当然,色彩的应用要有一定规范,要与产品色彩设计保证风格一致。

    • Android Developer Guide里的绘图方式,清新规范,很是喜欢。block与条框深浅设置、相邻block间文字的颜色对比。都有有可供借鉴与学习之处。
    【精华】技术文档工程师六大必杀技_第1张图片
    image.png

    【精华】技术文档工程师六大必杀技_第2张图片
    image.png
    • PDI Pendaho资料(http://www.pentaho.com/product/big-data-analytics)里面的绘图风格很是清新可爱。仔细观看,它家线条、箭头的用法;色调、线宽;图标的设计;表现手法。
【精华】技术文档工程师六大必杀技_第3张图片
image.png
  • Patience in problem-solving/troubleshooting
    动手能力--写文档不能光学理论,纸上谈兵,同样要勤于动手。优秀的文档工程师,也是一名合格的测试工程师,他们站在用户的角色去试用产品,提出疑问,这样写出的文档才实用,有深度。在动手过程中,Writer要有一点精神--执着。我们是writer,可能对技术操作细节不是很熟悉,但一定要有不耻下问的精神,问过之后,要有所积累记录。尽量同样的问题,避免问几遍。
  • Ability to interact with SMEs (Subject Matter Experts)
    在学习理解过程,不可或缺的一环是与人交流。交流技巧上,一则,要把握合适的时间,每个人都有他的本职工作,尽量避免在他焦头烂额的时候去打扰他们(比如提交代码时);另外,平日里,与他们建立良好的私交,也很重要。
    • 与产品经理交流,了解与挖掘出设计某一功能的意图,这些信息也就是topic-based writing里的[Purpose of a task].
    • 与项目经理交流,了解开发进度,协调资源。
    • 与测试交流,通过他们的demo, 快速了解feature的实现方法与操作方法。要时常去请教他们操作指示的细节。作为一名优秀的writer,脸皮要厚。要懂得迂回站术,测试在忙时,可以去问研发。研发没空,再揪住测试。
  • Knowledge about audience (这一点是我加的--TW非常需要培养的技能)
    文档为用户服务,只有了解读者群,站在他们的角度,分析他们的需求,才能总结出实用的task, 用他们能懂的语言将信息传递给他们。写用户文档不是描述一个个的产品feature,而是要把这些feature包装成用户日常工作中需要用到的task。

相关话题

  • 深圳文档工程师-市场需求与薪资分析
  • 点评:我亲历过的中英文文档工程师面试 (持续更新中...)
  • 各大招聘网站 (APP) 适用性评测

你可能感兴趣的:(【精华】技术文档工程师六大必杀技)