国产xxxx99真实实拍_久久不雅视频_高清韩国a级特黄毛片_嗯老师别我我受不了了小说

資訊專欄INFORMATION COLUMN

如何寫好技術(shù)文檔?

mengbo / 600人閱讀

摘要：衡量文檔的標(biāo)準(zhǔn)也是如此。及時(shí)更新不更新的文檔比更嚴(yán)重。寫文檔的工具方便快捷，可以導(dǎo)出各種格式的文件功能強(qiáng)大，需要部署，不方便傳遞文件

本文來自于公司內(nèi)部的一個(gè)分享。
在文檔方面，對內(nèi)的一些接口文檔主要是用swagger來寫的。雖然可以在線測試，比較方便。但是也存在著一些更新不及時(shí)，swgger文檔無法導(dǎo)出成文件的問題。
在對外提供的文檔方面：我主要負(fù)責(zé)做一個(gè)瀏覽器端的一個(gè)js sdk。文檔還算可以github地址，所以想把一些寫文檔的心得分享給大家。
1 衡量好文檔的唯一標(biāo)準(zhǔn)是什么？

Martin(Bob大叔)曾在《代碼整潔之道》一書打趣地說：當(dāng)你的代碼在做 Code Review 時(shí)，審查者要是憤怒地吼道：

“What the fuck is this shit?”
“Dude, What the fuck！”

等言辭激烈的詞語時(shí)，那說明你寫的代碼是 Bad Code，如果審查者只是漫不經(jīng)心的吐出幾個(gè)

“What the fuck?”，

那說明你寫的是 Good Code。衡量代碼質(zhì)量的唯一標(biāo)準(zhǔn)就是每分鐘罵出“WTF” 的頻率。

衡量文檔的標(biāo)準(zhǔn)也是如此。

2 好文檔的特點(diǎn)

簡潔：一句話可以說完的事情，就不要分兩句話來說。并不是文檔越厚越好，太厚的文檔大多沒人看。

準(zhǔn)確: 字段類型，默認(rèn)值，備注，是否必填等屬性說明。

邏輯性: 文檔如何劃分？ 利于查看。

demo勝千言: 好的demo勝過各種字段說明，可以復(fù)制下來直接使用。

讀者心: 從讀者的角度考慮, 方法盡量簡潔。可以傳遞一個(gè)參數(shù)搞定的事情，絕對不要讓用戶去傳兩個(gè)參數(shù)。

及時(shí)更新: 不更新的文檔比bug更嚴(yán)重。

向后兼容: 不要隨意廢棄已有的接口或者某個(gè)字段，除非你考慮到這樣做的后果。

建立文檔詞匯表：每個(gè)概念只有一個(gè)名字，不要隨意起名字，名不正則言不順。

格式統(tǒng)一：例如時(shí)間格式。我曾見過2017-09-12 09:32:23, 或2017.09.12 09:32:23或2017.09.12 09:32:23。變量名user_name, userName。

使用專業(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)允許請勿轉(zhuǎn)載,若此文章存在違規(guī)行為，您可以聯(lián)系管理員刪除。

轉(zhuǎn)載請注明本文地址：http://specialneedsforspecialkids.com/yun/89525.html

相關(guān)文章

  • 如何寫好技術(shù)簡歷 —— 實(shí)例、模板及工具

    摘要：在線簡歷生成工具，可以導(dǎo)出。技巧目前寫簡歷的方式有兩種普遍被認(rèn)可，一種是一種是。培養(yǎng)新人和帶團(tuán)隊(duì)其他項(xiàng)目項(xiàng)目該項(xiàng)目是，使用技術(shù)，完成功能。閱讀原文點(diǎn)擊查看簡歷模板。 工欲善其事必先利其器，這是自古以來的道理，所以如果想找到一份好的工作，一定要先整理一份好的簡歷。 模板 寫簡歷首先要有一個(gè)好的模板，我們做技術(shù)的不同于 UX,UED，我們不需要那么花哨，但是也需要整潔干凈。好的模板能讓你的...

    sunnyxd 評論0 收藏0

  • PHPer面試指南-程序員如何寫好一份簡歷？

    摘要：本書的地址程序員的簡歷在求職的時(shí)候，尤為重要，簡歷就是銷售自己的明信片，一份優(yōu)秀的簡歷，能為你帶來更多的面試機(jī)會。擴(kuò)展閱讀程序員簡歷應(yīng)該怎么寫面試時(shí)，如何向公司提問 本書的 GitHub 地址：https://github.com/todayqq/PH...程序員的簡歷在求職的時(shí)候，尤為重要，簡歷就是銷售自己的明信片，一份優(yōu)秀的簡歷，能為你帶來更多的面試機(jī)會。 我自己寫了不少了簡歷，...

    tabalt 評論0 收藏0

  • 作為前端開發(fā)，如何寫好一個(gè)簡歷

    摘要：項(xiàng)目地址需求來源通常在各個(gè)招聘網(wǎng)站，我們填寫完一些信息后，網(wǎng)站就可以幫助我們生成一個(gè)很不錯的簡歷。但是作為一名開發(fā)者，尤其是前端開發(fā)者，可能對這種簡歷并不滿意。，前端開發(fā)神器。最后，為了保護(hù)隱私。 背景 前一陣子，閑下來便開始著手做一個(gè)一直想做的東西--resume。經(jīng)過幾天業(yè)余時(shí)間的折騰，終于做出了一番模樣。Github項(xiàng)目地址：https://github.com/eternity...

    abson 評論0 收藏0

  • 作為前端開發(fā)，如何寫好一個(gè)簡歷

    摘要：項(xiàng)目地址需求來源通常在各個(gè)招聘網(wǎng)站，我們填寫完一些信息后，網(wǎng)站就可以幫助我們生成一個(gè)很不錯的簡歷。但是作為一名開發(fā)者，尤其是前端開發(fā)者，可能對這種簡歷并不滿意。，前端開發(fā)神器。最后，為了保護(hù)隱私。 背景 前一陣子，閑下來便開始著手做一個(gè)一直想做的東西--resume。經(jīng)過幾天業(yè)余時(shí)間的折騰，終于做出了一番模樣。Github項(xiàng)目地址：https://github.com/eternity...

    KunMinX 評論0 收藏0

發(fā)表評論

0條評論

最新活動
閱讀需要支付1元查看
<