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间文字的颜色对比。都有有可供借鉴与学习之处。
image.pngimage.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)
在学习理解过程，不可或缺的一环是与人交流。SME在对产品的认识层次上比TW更深入，与最终用户有直接的联系，知道产品解决的用户痛点。与他们交流，可以挖掘出非常多有价值的信息，让文档更加贴近用户。
交流技巧上，一则，要把握合适的时间，每个人都有他的本职工作，尽量避免在他焦头烂额的时候去打扰他们（比如提交代码时）；另外，平日里，与他们建立良好的私交，也很重要。- 与产品经理交流，了解与挖掘出设计某一功能的意图，这些信息也就是topic-based writing里的[Purpose of a task].
- 与项目经理交流，了解开发进度，协调资源。
- 与测试交流，通过他们的demo, 快速了解feature的实现方法与操作方法。要时常去请教他们操作指示的细节。作为一名优秀的writer，脸皮要厚。要懂得迂回站术，测试在忙时，可以去问研发。研发没空，再揪住测试。
-
Knowledge about audience/Ability to empathize with users (这一点是我加的--TW非常需要培养的技能）
文档为用户服务，只有了解读者群，站在他们的角度，分析他们的需求，才能总结出实用的task, 用他们能懂的语言将信息传递给他们。写用户文档不是描述一个个的产品feature,而是要把这些feature包装成用户日常工作中需要用到的task。
20210412回顾本文，发现前面链接可能国内访问不了，遂把内容贴出来。才发现这五点是I'd rather be writing的作者Tom Johnson总结的：
I offer these five skills or characteristics as absolute musts for the technical writer:
Facility with technology
You have to be somewhat technical, although there are many different kinds of technicalese. You may have a bent towards one of the sciences, and can understand the inner workings of cells or atoms. Or you may be web savvy and know how to interpret code. Or maybe you're just curious about how things work. You can learn technologies you don't understand, if you have the motivation. I personally enjoy learning about complicated systems. This understanding brings a sense of achievement and knowledge that is rewarding at the end of the day.Ability to write clearly
The essential skill of any technical communicator is to disambiguate (to use a word my father introduced to me the other day). Your core job will consist of taking complicated things and trying to explain them in easy-to-understand ways. You can't just pass off an explanation you only half understand. Writing about something (as opposed to talking about it) requires you to understand it thoroughly. Avoid passive sentences and long constructions. Go from old ideas to new. Define acronyms and avoid assumptions about what the user knows. Make the reader feel smart.Talent in showing ideas graphically
I underestimated the importance of using Visio until just a few months ago. Any time you can show an idea graphically, you score a hundred points with the reader. Almost everyone is a visual person. People understand better when you can communicate your ideas visually (and I'm not just talking about screenshots here, although they do count for something). It is surprisingly easy to create half-decent diagrams in Visio. They go a long way toward making your writing clear.Patience in problem-solving/troubleshooting
Unless you have patience, you'll never make it. I think 80 percent of IT work consists of problem solving. What do you do when you can't figure out how to do something? Do you slam your fist into your keyboard? Do you scream and curse when you can't immediately figure something out? It's amazing how you can see a seemingly impossible problem through with patience and persistence.Ability to interact with SMEs
I talked about this in my last podcast on Tech Writer Voices. Interacting with SMEs is one the most overlooked skills in technical writing. You have to be part investigative reporter, part journalist. You can't be shy about going after certain people to extract information. And you can't be too proud to ask the "dumb technical questions" that make engineers do double-takes. A lot of this interaction can come about if you're lucky enough to simply sit near SMEs
相关话题
