寫教學文件該注意的地方

[chiouss]

在竹貓上面可以看到很多熱心的網友願意貢獻自己的經驗來寫教學文章，實在是一件可賀可喜的事情。畢竟有些人 (像我) 就是懶得動手抓圖寫字，只會負責在人家的問題後面碎碎唸

不過寫教學文章很重要的一點就是要注重正確性，除了確定所寫的步驟可行之外還要確定你寫出來的內容 (說明、註解) 是正確的，這點通常是從官方的 manual (使用說明) 裡面來確認。

官方說明文件的正確性應該有九成以上，除非：

1. 官方說明文件太舊了，裡面說明和現有版本不符
2. 官方說明寫得很複雜難懂
3. 照著官方說明去做軟體沒辦法正常運作
4. 官方說明沒有寫到

因此，寫教學的時候如果和官方的說法不一樣要特別說明，像是

照官方的說法，這邊要 xxx 再 ooo 才對，但是這樣做太麻煩了，我發現 blahblahblah 就可以...

之類的，最好還附上官方的說明或是連結 (假如有線上文件的話) 來告訴其他人。

為什麼我特別強調這件事情呢？因為很多事情都是在網路上面以訛傳訛造成的，第一個人寫了錯誤的教學後面其他人看了也照抄照做，直到某天出問題了才發現是第一個人寫錯了。大家都會罵記者亂報導不實的消息不用負責任，應該不會希望哪天被人家在背後抱怨教學文件亂教亂寫吧？

--
以上只是一點心得和大家分享

[chiouss]

補充，竹貓上面常常拿來討論的 phpBB, Apache, PHP, MySQL, phpMyAdmin 這些東西在他們的官方網站上都有詳盡的線上的說明文件

• Apache: http://httpd.apache.org/docs/
• PHP: http://www.php.net/docs.php
• MySQL: http://dev.mysql.com/doc/
• phpBB: http://www.phpbb.com/support/
• phpMyAdmin: http://www.phpmyadmin.net/home_page/docs.php

Appserv, EasyPHP, XAMPP,... 這些都是 Apache + PHP + MySQL 再外加其他自己的程式包裝起來的，有問題應該看原廠的官方說明。