考虑PHP，文档工具推荐phpDocumentor吧。

管理和更新文档，如果是函数/类的 接口说明 部分，依赖文档工具可以自动更新即可。这也就提供了在功能变化时，能够简单更新文档的一个思路：如果软件的功能都是通过很简洁、单一的函数调用来实现的，那么 更新函数接口的文档==更新软件的功能文档 ，简单省事。

文档形式无非以下几种：

• 纯文本文档（INSTALL、README等这些根目录下附带的文件）
• HTML形式完整文档（这是主要的）
• Unix man pages（对php程序几乎用不到）

相信我，虽然有很多写文档指导，但铁一般的核心原则只有这一点：

文档必须让用户不阅读软件源码，就能了解程序开放的全部接口，学习程序所有的用法。

如果文档有任何语焉不详，用户必须翻源码才能找到一些没有提到的细节，那这个文档一定是失败的。所以一定要注意，文档必须：

• 每个开放给用户的函数/类，必须在文档中，准确描述其中每个参数/成员的取值
• 仅用于内部的函数/类，不要在文档中暴露给用户。可以另编简要的开发者文档作为记录
• 要有一个简要的Getting Started（入门），也许可以有一个详细些的Tutorial（教程）
• 要有FAQ（常见问题）去解答一些大尺度、共性的疑问
• 但FAQ不要搞得高大全，也不要把具体函数之内小尺度的问题混进来
• 真的很推荐加入一些Example（示例），很有用处，非常方便他人通过修改、扩展示例来当做入门方法

写文档，重要的在于参考别人写文档的经验。别人这么写，那么我去模仿一般不会错。我的推荐是Django的官方文档——这个例子很好的符合了上边说的 函数接口完整覆盖，外围教程简要描述 的原则。