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
相關話題
