技术文档工程师六大必杀技
2017-05-03 本文已影响205人
Joy的未来十年
Technical writing overview与Technical Writing Wikipedia对TW职业提供出了5点技能要求，总结得非常到位。另外，我也加上一条，凑成6点。
-
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间文字的颜色对比。都有有可供借鉴与学习之处。
image.png
image.png- PDI Pendaho资料（http://www.pentaho.com/product/big-data-analytics）里面的绘图风格很是清新可爱。仔细观看，它家线条、箭头的用法；色调、线宽；图标的设计；表现手法。
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。
相关话题
