今天的文章不是一個技術文，反而是探討身為一個軟體工程師，該怎麼撰寫相關的技術文件
鑑於 WFH (Work From Hoem) 習慣的興起，人與人面對面的溝通減少，這意味即時的訊息傳遞變少了，取而代之的是非同步的訊息傳遞，簡單來說就是技術文件。
好的技術文件能夠讓需要的人快速找到問題，解決疑惑，但是一個好的技術文件到底該怎麼寫，這部分其實非常困難，並不是向程式碼一樣可以 copy&paste 馬上看到成果的，反而是需要時間練習，將整個過程與思路消化起來，用自己習慣的語言與形式將其撰寫出來。
首先，作者非常推崇由 Google 撰寫的系列文章，Tech Writing Course，整個課程內容不到兩小時，從不同章節來跟大家分享如何撰寫技術文章
接者撰寫技術文章時，作者個人是喜歡 divio 這個平台，不過更重要的則是其推薦的分類模式，根據內容分類成四大項
1. Tutorials - 學習導向
2. How-To Guides - 問題解決導向
3. Explanation - 深度理解導向
4. Reference - 資運分享導向
Google: https://developers.google.com/tech-writing
Divio: https://www.divio.com/
最後寫作語法方面，作者認為寫出一個能夠被有效搜尋的文章是非常重要的，譬如透過 word 等方式上傳檔案到系統中反而是一個不利於搜尋的方式。
取而代之的是，作者認為可以採用 Markdown 類似的語法作為基礎去撰寫文章，這種方式對於維護與撰寫都相對容易
今天有任何 Diagrams 的畫圖需求，可以考慮使用 Mermaid 這套解決方案，對於 GitLab/Azure 的使用者來說，已經內建其中。 GitHub/Atlassian Confluence 則有相關的 Plugin 可以安裝使用
最後則是文章的樣版內容，針對特定的文章格式，已經有不少的範本可以參考，透過這些範本可以更清楚的去描述你的內容，讓整體文章看起來更佳簡潔與流暢
1. Software Architecture Review Template
2. Architecture Decision Record Template
3. Incident Postmortem Template
4. DevOps Runbook
5. Decision Template
6. Writing Guidelines
7. OKR Template
8. Etc.
有興趣的點選原文學習更多
https://medium.com/better-programming/best-practices-when-documenting-your-code-for-software-engineers-941f0897aa0
okr範本 在 [心得] OKR做最重要的事- 看板book - 批踢踢實業坊 的推薦與評價
本書由John Doerr所著，作者本身是一位創業投資家（ted有他演講的影片），
這本書名叫做OKR，全文是Objectives and Key Results，是一種管理公司的方法。
可想而知，這本書就是在推銷OKR，以大量的實例與使用者的回饋心得來說服讀者這套方
法的好處，以下我將省去實例故事的部分，盡可能將書中提到的基本OKR原則與效應列舉
出來：
一、專注投入優先要務
要提到OKR，勢必得先介紹一下何謂KPI（Key Performance Indicator），後者是一般公
司用來評估員工績效與設定目標的方法，通常是由上而下：老闆決定目標與每個員工應該
要做什麼（業績）。但OKR不一樣的地方在於，OKR是雙向的，管理階層決定了一個目標，
並且公佈出這個目標作為公司階級的目標，接下來各層級的員工在各自訂定能幫助公司達
到這個公司級目標的個人小目標，個人小目標與公司級目標是環環相扣的，也因為各員工
可以自己設立自身的OKR，因此OKR常常跟KPI做比較。前者是由下而上（或雙向），後者
是由上而下的。
稍為想像一下，一個從高層到前線的職位都朝著同一個大目標共同努力的公司，這種龐大
的能量跟向心力，正是OKR所帶來的超能力之一；而因為每一個個人目標與公司目標必定
要相互呼應，因此可以從各式各樣的目標中找出最優先呼應公司目標的工作來處理，
二、調和目標，造就團隊工作
第一點提到每個人設立自己的目標，那目標不會多而雜亂嗎？勢必是會的，但當每個目標
都是從一個大主題下來的分支時，每個人都會知道自己的目標對於大目標是有幫助的，也
會知道別人的目標對於大目標有著相當程度的幫助，因此每個人能完成目標都是極為重要
的事情，員工會基於這個想法進而互相幫助，以期公司能順利完成公司級的公司目標。
三、追蹤當責
這點要提到如何設計OKR，一個OKR是由兩樣東西組成，也就是Objectives（目標）和KeyR
esults（關鍵結果），關鍵結果是評斷目標達成與否的結果，換句話說，如果關鍵結果全
部達成了，那就表示這個目標達成了，舉例來說：若有一個目標設立為贏得印地500大賽
（賽車比賽），
那關鍵結果的設立就有下列五項，1.提高平均圈數2趴 2.完成10次風洞測試 3.縮短平均
進站時間1秒 4.減少進站失誤50趴5.每天練習進站1小時。
每一個關鍵結果最後的達成與否都會被全公司共同評分檢討，試著釐清為什麼沒有達成結
果的因素。
四、激發潛能，成就突破
為什麼OKR能夠造就偉大，這就和設立目標的方式有關，目標要抓在力有所及跟夢寐以求
之間，要比游刃有餘嚴苛，但比好高騖遠實際，書中提到需要努力的目標往往會讓員工更
專注，因此一組好的OKR會有好的目標，好的目標能告激發潛能，成就突破。
五、心得
以上四點是書中列舉OKR的四個超能力，我是將OKR的方法理解後再自己分類解釋進去的，
所以也許跟書中內容的排序有出入，但帶出的會是同一個結果，有關OKR的資訊若要查閱
本書，建議可以先看附錄，附錄有簡單明瞭的說明。
公司中最重要的是文化，OKR就是一種文化，保持目標極度開放、自由、透明，讓公司上
下一心的完成偉大的使命。看完本書我了解了偉大的公司是怎麼設立願景的，也希望我能
利用OKR改革目前所在的團隊；當然，書中有提到OKR是可以運用在各種面向的，但如何使
之有彈性就要看各位的靈活思考了。
最後評論本書，語調輕鬆，一開始會覺得書中一直重複特定的觀念，但看完會知道，這些
觀念就是OKR的核心，本書以故事跟心得為主，很適合輕鬆的閱讀，推薦給大家。
--
※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 49.218.12.113 (臺灣)
※ 文章網址: https://www.ptt.cc/bbs/book/M.1560886000.A.423.html
們是如何運用的。每本書都會為自己的人生態度、價值觀、生存意義層面做一定程度的改
變。我也不喜歡心靈雞湯的書籍，可是我還是認為每種書都還是有存在的價值，畢竟，思
緒邏輯還是由看過的每一本書共同形成的！！至少我這樣認為~~
※ 編輯: biemelo157 (49.218.12.113 臺灣), 06/19/2019 12:53:03
※ 編輯: biemelo157 (49.218.12.113 臺灣), 06/19/2019 18:32:52
※ 編輯: biemelo157 (49.218.12.113 臺灣), 06/19/2019 22:26:29
... <看更多>