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