第一屆 LINE Taiwan Technical Writing Day

大家好我是 LINE 台灣的 Technical Evangelist – Evan Lin 。LINE 台灣開發者關係與技術推廣團隊 (Developer Relations) 除了對外部的開發者推廣之外,有另一個很重要的使命就是希望能夠透過相關的開發者活動能夠激發內部的開發者的潛力,不論是透過內部訓練或是相關的活動。而這次的活動就是希望能增進內部開發者技術文件的寫作能力外,更重要的是希望能夠增加開發人員彼此的溝通技能。也期許透過本次的訓練能夠增進內部開發者彼此技術文件分享的能力,也希望增進對外文件的撰寫品質與數量能夠更好。

什麼是技術寫作日 (Technical Writing Day)

身為開發者對於文件的寫作總是有許多困難的地方,不論是不知道該如何撰寫之外就是經常不確定如何撰寫讓使用者能夠淺顯易懂的文件。開發者經常認為程式碼能夠表達許多事情,而無法有效的將讀者或是使用者需要的資訊寫在文件上。 在開發者部落格寫作上,開發者們經常不知道該如何安排他們的文章內容,順序與如何有效地表達。 

技術寫作日其實是一個由 LINE 技術文件作家 (Technical Writer) 團隊所籌畫的一系列活動。日前不僅在韓國有舉辦過(請參考這篇文章),其實在日本也舉辦過。這次很開心能遠從韓國與日本邀請到他們來到台灣舉辦。 不僅僅邀請了所有的內部開發者,連經常需要撰寫技術文件的團隊也都邀請一起來了解,並且增進我們技術文件的寫作能力。 

關於技術寫作日的課程簡介

技術寫作日是一整天的訓練課程包括了早上的基礎訓練之外,下午有許多進階的訓練課程。在這裡簡單的分享幾個重要的課程與相關的介紹,分享給各位讀者。

Introduction to Technical Writing

首先登場的是由 Technical Writing Team Lead 所帶來的 Introduction to Technical Writing 。透過帶出軟體開發的流程 ( Concept, Analyze, Design, Development and Test ) 帶出其實技術寫作應該視為軟體開發的流程。需要有足夠的構思,設計之外,更需要詳細寫作後的測試。也就是重新檢視寫作內容,測試所有範例程式碼確認所有技術細節都是正確並且是最新的狀態。

LINE 的開發者有以下幾種方式是透過技術文件方式來做溝通:

  • Wiki: 為開發者內部溝通最主要的管道,透過可以容易分享,共同編輯的 Wiki 系統。 許多的技術相關的溝通與討論往往是在 Wiki 上面而不是 Email ,讓許多的變更與分享更加有效果也能夠允許更多人開發同仁能夠一起協作。
  • README 文件: 每個專案的負責人都會撰寫相關的介紹文件,不論該專案是內部專案還是開源的專案。
  • API 文件: 平台團隊與 SDK 團隊經常會準備的相關技術文件,不論是內部專案或是外部的公開 API 。都會有清楚的 API 文件。

這些部分的文件撰寫都很需要 Technical Writing 的技術寫作概念的持續增進。

Introduction to P.O.W.E.R. Writing

第二部分介紹的是相當有用的概念 P.O.W.E.R Writing , 而 POWER 其實是五個字的縮寫。

  • Preparing
  • Organizing
  • Writing
  • Editing
  • Reviewing

在寫作技術文件的時候,透過使用 POWER 的原則可以讓寫作更加的順利,也可以增加文章的可讀性與減少錯誤的產生。這五個字就像是一個心法一樣,相當的重要而且相當的有用。方便我們可以準備技術的素材,組織整個文章架構,寫作更清楚的文字,透過使用更易懂的方式來修改,最後要不斷的審核。相當有用的一堂課程。

Writing Blogs

這一段的教學主要是簡介 LINE Engineering Blog 的發布流程,與為何要撰寫 Engineering Blog 與有哪些好處。 

為何要撰寫 Engineering Blog 的部分。透過將技術文件分享在文字的過程,可以從頭到尾仔細地審視了解的技術,遇到的問題與解決的方法。這邊也鼓勵每個開發者都應該要試著撰寫部落格,除了可以增進每個人對於技術溝通能力之外,更可以清楚了解自己是不是還有不清楚的地方。 而且相當建議每個開發者透過公司的平台來發表相關的文件。因為除了平台的比較受到大家的重視之外,每一篇文章的發行需要透過許多專家層層的把關。從每一個文字的校對到資訊安全的審核,讓每一位開發者只需要專注在自己的文字表達部分。

每個開發者透過 Engineering Blog 還可以獲得許多同仁對於技術文字表達方式與內容的排列方式有著更深層的交流,真是獲益良多。

Organizing and presenting information using the wiki

Wiki 是 LINE 開發者作為內部技術溝通很重要的一個工具,不論是會議記錄,產品規格,甚至到部落格文章草稿。如何能夠有效地呈現卻是困難的,所以如何展現與擺放足夠的資訊在 Wiki 上面就是一門學問。這一場分享中,講者講解了如何透過 Wiki 的一些工具告訴大家該如何來有效的將資訊作為有效的相互鏈結,分享並且協作的方式。最後講者也分享一個很有趣的例子:

就在出國六個小時前,忽然找不到護照。不論在行李箱裡面,或是他的辦公桌上都找不到,最後卻在舊衣服堆裡面發現了。

這個故事就告訴我們,除了資訊的足夠之外如何有效地「擺放」你的 Wiki 頁面讓大部分的人能夠透過關鍵字或是階層式資料夾排列方式來尋找到文件就是一門大學問。

Writing developers guide

如何要開始撰寫開發者指南,永遠都是開發產品或是微服務 (microservices) 的很痛苦的地方。而這一段分享就是透過分享如何撰寫微服務的開發者指南來分享該文件應有的架構與特點。撰寫開發者指南講者建議就要由讀者的面向來出發。如果要撰寫一個微服務的安裝手冊,安裝需求與如何安裝就是每個使用者第一次看文件馬上會著眼的地方。那麼就開從這些地方開始準備,而且要不斷的反覆測試你的開發者指南,並且清楚地記錄下每一個容易犯錯的地方。不要讓使用者發生了錯誤而不知道該怎麼自行解決問題,這就是開發者指南最重要的幾個部分。

總結

身為 LINE台灣資深開發技術推廣工程師(Technical Evangelist) ,深刻的認為撰寫良好的技術文件的技巧也就是在磨練著開發者彼此對於技術的溝通能力。許多的開發者在文件撰寫上往往不知道該如何開始,如何將整個來龍去脈做有效與系統化的呈現。 透過技術寫作日的訓練,希望就是能夠讓開發者們的溝通能力更上一層樓。彼此能夠更精進文件撰寫能力與系統思考的組織力。 開發者關係與技術推廣部 (Developer Relation) 將持續引進與推逛更多內部開發者的相關課程訓練,對外也將持續的努力提供更好的,更友善的 「LINE開發社群計畫」。

關於「LINE開發社群計畫」

LINE今年年初在台灣啟動「LINE開發社群計畫」,將長期投入人力與資源在台灣舉辦對內對外、線上線下的開發者社群聚會、徵才日、開發者大會等,預計全年將舉辦30場以上的活動。歡迎讀者們能夠持續回來察看最新的狀況。詳情請看 2019 年LINE 開發社群計畫活動時程表 (持續更新)

LINE台灣持續招募中

你是有能力的開發者嗎? 如果喜歡開發系統卻對於文件撰寫不知道該如何起頭,在 LINE 台灣會有相關的課程與訓練有系統的指導內部的開發者。想要加入我們嗎? 快到以下的地方尋找你有興趣的職缺。