資訊專欄INFORMATION COLUMN
摘要：衡量文檔的標(biāo)準也是如此。及時更新不更新的文檔比更嚴重。寫文檔的工具方便快捷，可以導(dǎo)出各種格式的文件功能強大，需要部署，不方便傳遞文件
本文來自于公司內(nèi)部的一個分享。1 衡量好文檔的唯一標(biāo)準是什么？
在文檔方面，對內(nèi)的一些接口文檔主要是用swagger來寫的。雖然可以在線測試，比較方便。但是也存在著一些更新不及時，swgger文檔無法導(dǎo)出成文件的問題。
在對外提供的文檔方面：我主要負責(zé)做一個瀏覽器端的一個js sdk。文檔還算可以github地址，所以想把一些寫文檔的心得分享給大家。
Martin(Bob大叔)曾在《代碼整潔之道》一書打趣地說：當(dāng)你的代碼在做 Code Review 時，審查者要是憤怒地吼道：
“What the fuck is this shit?” “Dude, What the fuck！”
等言辭激烈的詞語時，那說明你寫的代碼是 Bad Code，如果審查者只是漫不經(jīng)心的吐出幾個
“What the fuck?”，
那說明你寫的是 Good Code。衡量代碼質(zhì)量的唯一標(biāo)準就是每分鐘罵出“WTF” 的頻率。
衡量文檔的標(biāo)準也是如此。
2 好文檔的特點簡潔：一句話可以說完的事情，就不要分兩句話來說。并不是文檔越厚越好，太厚的文檔大多沒人看。
準確: 字段類型，默認值，備注，是否必填等屬性說明。
邏輯性: 文檔如何劃分？ 利于查看。
demo勝千言: 好的demo勝過各種字段說明，可以復(fù)制下來直接使用。
讀者心: 從讀者的角度考慮, 方法盡量簡潔?？梢詡鬟f一個參數(shù)搞定的事情，絕對不要讓用戶去傳兩個參數(shù)。
及時更新: 不更新的文檔比bug更嚴重。
向后兼容: 不要隨意廢棄已有的接口或者某個字段，除非你考慮到這樣做的后果。
建立文檔詞匯表：每個概念只有一個名字，不要隨意起名字，名不正則言不順。
格式統(tǒng)一：例如時間格式。我曾見過2017-09-12 09:32:23, 或2017.09.12 09:32:23或2017.09.12 09:32:23。變量名user_name, userName。
使用專業(yè)詞語：不要過于口語化
3 總結(jié): 寫出好文檔要有以下四點邏輯性：便于查找
專業(yè)性: 值得信賴，質(zhì)量保證
責(zé)任心：及時更新，準確性，向后兼容
讀者心：你了解的東西，別人可能并不清楚。從讀者的角度去考慮，他們需要什么，而不是一味去強調(diào)你能提供什么。
4 寫文檔的工具markdown: 方便快捷，可以導(dǎo)出各種格式的文件
swagger: 功能強大，需要部署，不方便傳遞文件
文章版權(quán)歸作者所有，未經(jīng)允許請勿轉(zhuǎn)載,若此文章存在違規(guī)行為，您可以聯(lián)系管理員刪除。
轉(zhuǎn)載請注明本文地址：http://systransis.cn/yun/89525.html
摘要：在線簡歷生成工具，可以導(dǎo)出。技巧目前寫簡歷的方式有兩種普遍被認可，一種是一種是。培養(yǎng)新人和帶團隊其他項目項目該項目是，使用技術(shù)，完成功能。閱讀原文點擊查看簡歷模板。 工欲善其事必先利其器，這是自古以來的道理，所以如果想找到一份好的工作，一定要先整理一份好的簡歷。 模板 寫簡歷首先要有一個好的模板，我們做技術(shù)的不同于 UX,UED，我們不需要那么花哨，但是也需要整潔干凈。好的模板能讓你的...
摘要：本書的地址程序員的簡歷在求職的時候，尤為重要，簡歷就是銷售自己的明信片，一份優(yōu)秀的簡歷，能為你帶來更多的面試機會。擴展閱讀程序員簡歷應(yīng)該怎么寫面試時，如何向公司提問 本書的 GitHub 地址：https://github.com/todayqq/PH...程序員的簡歷在求職的時候，尤為重要，簡歷就是銷售自己的明信片，一份優(yōu)秀的簡歷，能為你帶來更多的面試機會。 我自己寫了不少了簡歷，...
摘要：項目地址需求來源通常在各個招聘網(wǎng)站，我們填寫完一些信息后，網(wǎng)站就可以幫助我們生成一個很不錯的簡歷。但是作為一名開發(fā)者，尤其是前端開發(fā)者，可能對這種簡歷并不滿意。，前端開發(fā)神器。最后，為了保護隱私。 背景 前一陣子，閑下來便開始著手做一個一直想做的東西--resume。經(jīng)過幾天業(yè)余時間的折騰，終于做出了一番模樣。Github項目地址：https://github.com/eternity...
摘要：項目地址需求來源通常在各個招聘網(wǎng)站，我們填寫完一些信息后，網(wǎng)站就可以幫助我們生成一個很不錯的簡歷。但是作為一名開發(fā)者，尤其是前端開發(fā)者，可能對這種簡歷并不滿意。，前端開發(fā)神器。最后，為了保護隱私。 背景 前一陣子，閑下來便開始著手做一個一直想做的東西--resume。經(jīng)過幾天業(yè)余時間的折騰，終于做出了一番模樣。Github項目地址：https://github.com/eternity...
閱讀 1035·2021-11-23 10:11
閱讀 3869·2021-11-16 11:50
閱讀 937·2021-10-14 09:43
閱讀 2722·2021-10-14 09:42
閱讀 2723·2021-09-22 16:02
閱讀 1068·2019-08-29 10:57
閱讀 3386·2019-08-29 10:57
閱讀 2276·2019-08-26 13:52
