推 content71: 說的很好 10/04 22:28
推 Ghamu: 最低標準 能讓未來的自己看懂 10/05 00:06
→ viper9709: 推樓上 10/05 00:14
推 TAKADO: 推2樓 10/05 23:56
→ meowyih: 據統計，九成以上的程式說明文件最後都只有自己會看XD 10/06 12:35
可以從幾個角度去思考
1. 給誰看
工程師、PM、PR、業主。需要的資訊程度不同。
給同部門或者跨部門的工程師看，需要的資訊程度也不同。要考慮讀者背景差異。
2. 文件預計達成的目的為何
讀者可以從文件中找到或學會甚麼?
或是為了符合某些規定 CMMI
3. 文件更新頻率
文件內容最好不要跟實際落差太大。
太細或者有可能變更的資訊，就要考慮一下做法。
例如code level的資訊都用註解為主，再用工具把註解撈出來自動編成文件。
舉例來說：技術文件
對象：部門內後來加入的新人
目的：了解程式架構，方便新人快速上手。
對象：不同部門的工程師
目的：了解如何使用這套Lib/API
上面這個定位跟對象搞清楚，網路上就有很多文件範本可以參考。
※ 引述《jonjes (HONOKA)》之銘言：
: 最近寫文件、架構或畫流程圖的機會變多了
: 雖然同事說只要找個專案外的第三者來看，對方能懂就好了
: 但還是很猶豫文件到底要定義到多細才好？
: 像func name 、func用途、參數、該參數的用途等
: 一般還會加個後續處理要做什麼嗎
: （感覺這比較像是需求文件、而不是技術文件該加的）
--
※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 118.169.209.30
※ 文章網址: https://www.ptt.cc/bbs/Soft_Job/M.1538660362.A.248.html