[請益] 怎樣的文件才算好？

[jonjes (HONOKA)]

最近寫文件、架構或畫流程圖的機會變多了

雖然同事說只要找個專案外的第三者來看，對方能懂就好了

但還是很猶豫文件到底要定義到多細才好？

像func name 、func用途、參數、該參數的用途等

一般還會加個後續處理要做什麼嗎
（感覺這比較像是需求文件、而不是技術文件該加的）

--
※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 111.185.154.161
※ 文章網址: https://www.ptt.cc/bbs/Soft_Job/M.1538656299.A.0BB.html
→ cha122977: 看了可以更快了解程式碼就算不差了
→ atpx: 看給誰看的
推 enthos: https://doc.dpdk.org/guides/prog_guide/
推 RunRun5566: 細節不用寫文件，寫測試就好
推 Argos: 你可以參考一下各大開源套件的Doc
推 guest0710: 個人想法 先確定大項有寫清楚 再寫細節
→ guest0710: 最討厭重點跟細節混雜在一起 很長的文件XD
→ landlord: 重點是文件出去後，寫的人跟看的人還會不會溝通
→ landlord: 文件的目的是為了幫助溝通、了解、還是白紙黑字責任範圍
→ Darkword1987: 有隨時間update的文件
→ feeya: 文件直接寫在註解
推 brianhsu: function 或 restful api 的話給外部用的要有文件說明用
→ brianhsu: 途，參數，注意事項會比較好。內部實作可能會一直更動，
→ brianhsu: 我是覺得不一定要文件，但命名之類的要顧好。
→ dreamnook: input output 用途說明
→ y3k: 能幫助看的人快速補齊所需知識的文件 才是好文件
→ y3k: 要達到這個標準 首先要問自己 要寫給誰看?prerequisite如何
→ y3k: 正所謂因材施教也
推 lovebridget: 老闆覺得好的那樣 才算好
→ lovebridget: 適用於任何情況 任何問題
推 f124: 老闆看了覺得好的就是好
推 uiop019: 上網找找SAP ERP的系統文件，那樣的內容就夠了