社區使用指南如何撰寫一篇高品質的 Wiki 文章？
說明
撰寫一篇 Wiki 文章，是一件很簡單的事情，隨便從文檔或者 Google 中復制黏貼進來，就是一篇 Wiki。
然而，撰寫一篇「高品質」的 Wiki 文章，卻不是一件容易的事情，我們一起來探討下。
如何定義高品質？
一篇高品質的社區 Wiki 除去基本的技術信息，還應該具備以下這些特性：
- 1. 寫好開頭
文章最開始的地方是最重要的，好的開頭應該能快速讓讀者身臨其境，最好是由一個問題，或者一個設想中的案例引起全文。
- 2. 示例代碼
大部分的 Wiki 文章需要代碼演示，代碼示例越多、越實用，讀者就會更好理解。另外代碼還需配帶輸出內容，這會使代碼看起來更加直觀。代碼示例應該是撰寫 Wiki 時設計的重點。
- 3. 經驗分享
編程經驗分享，這些是 含金量 最高的，也與文檔區分開。分享的經驗，可以是過往編程的經驗，也可以是通過閱讀大量文章并總結、親自測試過的經驗。
- 4. 最佳實踐
以傳播更好的編程實踐為目的，我們應該讓新手在學習 Wiki 時養成一些 編程好習慣，例如 PHP 中函數允許傳參數組，但是這種做法會降低代碼的可讀性，撰寫 Wiki 時就應加入提醒：「實際開發中，我們應該避免這么做。并且附上理由」。最佳實踐也可以從大量的文章閱讀中獲取到。
好的 Wiki 文章讀起來一氣呵成，并且感覺滿文都是干貨，猶如一個經驗老到的編程高手在語重心長的與你分享他枝繁葉茂的知識。
第 1 和 2 也許比較好實現，但是第 3 和 4 卻是需要下點功夫才能做到，接下來推薦一個方法。
參考
撰寫時，有一個技巧可以推薦給大家，那就是：
站在巨人的肩膀上。
具體來講就是參考優秀的文獻。每一門技術可參考的資源都不一樣，但是基本按照以下分類去尋找，都能定位到一些很棒的參考資料：
- 官方文檔/教程（文檔中有用戶評論更佳）；
- 搜索 Stackoverflow 「關于某個 Wiki 話題」，前 10 ~ 20 個問題；
- 閱讀 Google 搜索「關于某個 Wiki 話題」，前 10 ~ 100 篇文章；
- 社區優秀的免費和付費書籍（如果有的話）；
- 優秀的出版書籍（如果有的話）。
撰寫一篇 Wiki 文章時，先閱讀這些資料，能為我們帶來很多靈感。有時甚至能來勾起我們追憶過往經驗，這樣寫起文章來就會文思如泉涌。同時，這個「做功課」的過程，對撰寫者的學習也有非常棒的助益，因為你會被動地去獲取到許多「延伸知識」。
檢測清單
以下是一個 Wiki 文章撰寫時的檢測清單，可以用來自檢：
- 是否有一個簡單易懂的開頭？（可以提一個問題，或者場景描述）
- 示例代碼是否直接易懂？
- 示例代碼是否都有附帶輸出？
- 是否查閱了相關文檔和書籍？
- 是否閱讀了 Stackoverflow 上相關問題？
- 是否閱讀了 Google 搜索上相關文章？
- 是否還能分享更多的經驗和技巧？
- 是否有編碼「最佳實踐」可以分享？
提交 Wiki 前，做到上面列表里的每一項，文章的品質自然不會低。并且隨著撰寫經驗的積累，你會越來越優秀。
結語
撰寫 Wiki 的目的是為了學習和總結。如果不給自己提高要求，也不仔細做功課、做調研，那就本末倒置了。
我們的目標絕對不是「完成一篇 Wiki」這么簡單，而是：
撰寫一篇高品質的 Wiki，并在此過程中職業技能得到提升。
筆者為 wangan 的站長，技術涉獵比較廣泛，Wiki 功能開發的初衷也是為了鞏固個人所學知識。最后，歡迎有興趣的同學一起參與學習和分享。
推薦文章：