好的项目文档能够帮助人们更好的沟通：

对于开发者自己而言：
- 在项目完成后续的任何时间里，都能够清晰的看懂之前的代码逻辑
- 其他人通过阅读你的代码能够对你个人能力做出判断
- 鼓励其他人为你的代码做出贡献
对于其他开发者而言：
- 其他人可以轻松使用你的代码并以此为基础继续开发
对于整个社区而言：
- 推动科学进步
- 鼓励开源
- 增加项目的可重现性与透明度

一份好的项目文档应该包括：

包含一份README文档：
- 一个简单的项目介绍
- 项目的安装说明
- 简单的使用教程
允许其他人反馈问题
写API文档：
- 函数的作用
- 函数的参数及其说明
- 函数的返回值
代码都要写注释
阐述编码约定，例如文件组织结构、注释和命名约定
列出所有代码贡献者
说明项目遵循的许可规则
给出项目的引用信息
给出项目负责人的联系方式
列出所有的主要的历史版本及其修改信息

一份常用的README的markdown样例：

Project Title
------
    
Description
------
One Paragraph of project description goes here.

Prerequisites
------
* List all the dependencies.
* List what to install and how to install it.

Installation
------
* A step by step instructions on how to install the software.    
`Example that shows how the software works.`

Contributing
------
Issue Tracker: github.com/project/issues.

License
------
Provide Licensing information.

Citation
------
* How this software can be cited.
* Provide a DOI that was generated.

Contact
------
* Link to e-mail address or URLs.