之前写过一点小东西，为了让它更成型一点，我决定给它写个文档。可是这难倒我了，以前压根就没写过正规的文档。目前写东西都是人肉写文档的，直接HTML页面或者Github WIKI。写久了之后就发现这样实在是太不便于管理了，如果某个功能有更新，想修改文档还得找一下，还指不定都找全了（当然可能是我写文档的思路有问题）。
所以在这请教一下大家，如何给程序写文档，因为写的是PHP的程序，希望大家能偏向这边答一点，虽然说写文档这东西跟语言真的无关就是了。以及希望大家从以下几个方面回答问题：
- 怎么写好文档
- 用什么写文档
- 如何方便的 管理/更新 文档
- 写文档需要注意什么
可以考虑轻量级标记语言。 markdown, restructuredtext (rst) 等。
- 纯文本，可以和代码一起管理。
- 可以转换成多种格式发布。
- 格式简单，易学，高效。
推荐朴灵的http://html5ify.com/doxmate/
apigen你可以试试...
API文档的话推荐一下doxygen，
其它文档推荐一下markdown。
考虑PHP，文档工具推荐phpDocumentor吧。
管理和更新文档，如果是函数/类的接口说明部分，依赖文档工具可以自动更新即可。这也就提供了在功能变化时，能够简单更新文档的一个思路：如果软件的功能都是通过很简洁、单一的函数调用来实现的，那么更新函数接口的文档==更新软件的功能文档，简单省事。
文档形式无非以下几种：
- 纯文本文档（INSTALL、README等这些根目录下附带的文件）
- HTML形式完整文档（这是主要的）
- Unix man pages（对php程序几乎用不到）
相信我，虽然有很多写文档指导，但铁一般的核心原则只有这一点：
文档必须让用户不阅读软件源码，就能了解程序开放的全部接口，学习程序所有的用法。
如果文档有任何语焉不详，用户必须翻源码才能找到一些没有提到的细节，那这个文档一定是失败的。所以一定要注意，文档必须：
- 每个开放给用户的函数/类，必须在文档中，准确描述其中每个参数/成员的取值
- 仅用于内部的函数/类，不要在文档中暴露给用户。可以另编简要的开发者文档作为记录
- 要有一个简要的Getting Started（入门），也许可以有一个详细些的Tutorial（教程）
- 要有FAQ（常见问题）去解答一些大尺度、共性的疑问
- 但FAQ不要搞得高大全，也不要把具体函数之内小尺度的问题混进来
- 真的很推荐加入一些Example（示例），很有用处，非常方便他人通过修改、扩展示例来当做入门方法
写文档，重要的在于参考别人写文档的经验。别人这么写，那么我去模仿一般不会错。我的推荐是Django的官方文档——这个例子很好的符合了上边说的函数接口完整覆盖，外围教程简要描述的原则。
要写好文档，并不是一件容易的事，你平常应该做写作的练习才成，不然要憋出点文字出来真心不容易，明明知道是怎么回事，但是却真的不能用文字表达出来，还是挺难受的。所以要写文档，平常应该多注意练习自己的写作技巧，最好是坚持写博客什么的。
你可以订阅褪墨的博客，多读读他的文章，很有帮助，比如《15条技巧提高你的写作技巧》
用什么写文档
至于使用什么工具嘛，我用过的比较简单的就是 Sphinx 了，使用 reStructedText 来写作还是比较方便的，表达能力也挺强，相比于 Markdown，它支持更多高级语法，尤其是用来写项目的文档，非常方便。不足的是中文的静态搜索不支持，不过可以使用 Google 搜索替代。
PS: 其实国内的大牛有做一些中文搜索方面的改进包，你可以搜索下。
如果是给 Python 项目写文档，那 Sphinx 就更有优势了，可以方便的生成 API 文档。
Sphinx 还可以方便的转成 html, chm 等包，当然也可以转成 pdf。
使用 Sphinx 生成的文档，可以发布在 https://readthedocs.org/ 上，当然，你也可以发布在任何支持静态页面的服务上，比如 Github，Dropbox, Gitcafe 什么的。
如果你的项目是开源项目，托管在 Github 上，那可以直接使用 Github Wiki 来写文档，如果是国内的服务，可以使用 Gitcafe Wiki 也相当不错。
如果你觉得 Sphinx 语法太繁琐，可以考虑使用 Markdown，参考今天我读的一篇文章：http://www.ideawu.net/blog/archives/774.html
如果是使用 Sphinx 等工具来写文件，你的文档就是纯文本文件了，当然可以使用任何版本管理工具直接管理，比如 Git。
我们公司之前还有用 http://moinmo.in/ Wiki 来写文档，效果也不错。
至于写文档需要注意什么，我觉得只要条理和结构清晰，不要有错别字什么，不要有逻辑错误什么的，也没有什么好注意的。你不用一口吃个胖子，文档是一点点累积起来的，逐步改进就好了。关键还是要把东西推出来，等有人用你的东西了，你可以根据反馈，逐步的补充你的文档。