讓寫技術(shù)文章成為大家的一種工作習(xí)慣和方式史辙。
解決問題##
促進(jìn)個(gè)人汹买，團(tuán)隊(duì)，大團(tuán)隊(duì)技術(shù)博客的建設(shè)：
- 習(xí)慣成自然聊倔， 先要有習(xí)慣晦毙，然后才能成為自然。
- 習(xí)慣要容易養(yǎng)成耙蔑，利用技術(shù)人員寫筆記做積累的特點(diǎn)和相應(yīng)項(xiàng)目需要技術(shù)文檔的特性见妒，和工作緊密結(jié)合，讓寫文章就像寫代碼一樣甸陌。
- 尋找一種方便的方式將每個(gè)人以及項(xiàng)目的積累以標(biāo)準(zhǔn)整理輸入徐鹤。
- 積少成多，建立機(jī)制自然的匯聚邀层，讓每個(gè)人是小溪返敬，小團(tuán)隊(duì)是小河，大團(tuán)隊(duì)的ATA是我們的大江寥院。
- 思想和筆記需要一定的積累和加工劲赠，按照寫書的思路，讓大家有合作編輯和評審的參與感秸谢，才能有高質(zhì)量的文章產(chǎn)出凛澎。
建議##
以MarkdownPad + Pandoc + Sphinx + Git的的標(biāo)準(zhǔn)方式推進(jìn)，這是目前很多開源軟件的技術(shù)文檔的協(xié)作方式估蹄。
技術(shù)特點(diǎn)###
以git管理文章內(nèi)容塑煎，技術(shù)人員很習(xí)慣也也便于管理。
以Markdown為文章格式臭蚁，MardownPad等工具很適合大家本地編寫最铁。
Pandoc可以做各種格式的轉(zhuǎn)換讯赏，比如輸出層pdf。
Sphinx可以方便講各種文章以書籍的格式整理冷尉，并產(chǎn)出高質(zhì)量的在線閱讀格式漱挎。
很好的表格支持，markdown對table支持不夠雀哨，sphinx對table以及自定義table有很強(qiáng)的支持磕谅。
具體可參考示范。
期望目標(biāo)##
每個(gè)人以這種方式做平時(shí)的技術(shù)筆記整理雾棺，讓個(gè)人養(yǎng)成習(xí)慣膊夹。團(tuán)隊(duì)以這種方式像協(xié)作寫書一樣做團(tuán)隊(duì)技術(shù)博客文集，團(tuán)隊(duì)之間形成良性競爭捌浩，看哪個(gè)團(tuán)隊(duì)的文集產(chǎn)出和質(zhì)量最高割疾。
這些產(chǎn)出都會輸出到團(tuán)隊(duì)的ATA上，同時(shí)也能成為自身團(tuán)隊(duì)的技術(shù)積累嘉栓。
這種方式也可以向整個(gè)技術(shù)部推薦，進(jìn)而成為集團(tuán)內(nèi)標(biāo)準(zhǔn)的技術(shù)文檔管理規(guī)范拓诸。
如何更好的激勵(lì)##
需要大家更多的意見...
示例和源碼##
安裝
- 安裝pandoc侵佃，http://www.pandoc.org/
- 安裝python和easy_install.
-
運(yùn)行easy_install安裝sphinx和pip
easy_install sphinx
easy_install pip
這個(gè)過程有失敗可以多試驗(yàn)幾次。
- 在文檔目錄里奠支，運(yùn)行make clean ; make html構(gòu)建文檔
參考資源##
Makedown 本地工具： MarkdownPad
Pandoc： www.pandoc.org（Sphinx 依賴）必須先安裝馋辈。
Sphinx: http://sphinx-doc.org/ 具體參考Sphinx安裝。 依賴python, pip, pandoc.
