阮一峯：中文技術文檔的寫做規範

不少人說，不知道怎麼寫文檔，都是憑着感受寫。

網上也不多有資料，教你寫文檔。這已經影響了中文軟件的發展。

英語世界裏，文檔很是受重視，許多公司和組織都有本身的文檔規範，清楚地規定寫做要求，好比微軟、MailChimp、Apple、Yahoo、docker、Struts 等等（維基百科有一份完整的清單）。中文的也有很多，但都不使人滿意，要麼太簡單，要麼不太適用。

我就動手，參考上面的規範，也結合本身的實踐，總結了一份簡單的《中文技術文檔的寫做規範》。

1. 標題
2. 文本
3. 段落
4. 數值
5. 標點符號
6. 章節結構

我但願，這樣能夠拋磚引玉，讓更多人重視文檔，進而真正出現你們廣泛接受的文檔規範。

下面是關於寫做風格的一個片斷。歡迎提交 Issue 和 PR 補充。

=================================

寫做風格

（摘自《中文技術文檔的寫做規範》）

若是使用了被動語態，應考慮更改成主動語態。

不使用非正式的語言風格。

用對"的"、"地"、"得"。

使用代詞時（好比"其"、"該"、"此"、"這"等詞），必須明確指代的內容，保證只有一個含義。

名詞前不要使用過多的形式詞。

句子的長度儘可能保持在20個字之內；20～29個字的句子，能夠接受；39～39個字的句子，語義必須明確，才能接受；多於40個字的句子，在任何狀況下都不能接受。

閱讀全文直接點擊：http://click.aliyun.com/m/9973/