README 书写指南 version 1.0

背景(why)

我们在Github上提交了一个项目, 为了更好的改进, 总是希望有更多人去使用并积极反馈, 帮助我们的项目更快更好的迭代.因此, 为了方便他人的使用以及协助我们开发迭代, 就需要写一个文档介绍关于这个项目的各方面信息. 我们把这个文档就命名为README. README的格式有很多, .TXT, .md, .doc等等.

README is a great face of your project!

内容(what)

README通常包含以下内容:

  • Configuration instructions
  • Installation instructions
  • Operating instructions
  • A file manifest (list of files included)
  • Copyright and licensing information
  • Contact information for the distributor or programmer
  • Known bugs
  • Troubleshooting
  • Credits and acknowledgments
  • A changelog (usually for programmers)
  • A news section (usually for users)

根据项目不同, README包含的内容也会各有侧重点:

  • 如果是软件, 应该包含installation.
  • 如果是open-source project, 最好包含如何获取最新版本.

通常我们要依照5W1H原则.
README各个部分的顺序安排也不尽相同, 以下是我的个人建议:

  • Project name
  • Introduction.(What)
  • Code examples.
  • Motivation.(Why)
  • Configuration.(Where)
  • Installation and Operating instrcutions.(How)
  • Authors information.(Who)
  • Copyright and licensing information.
    • 目前分为三种license
  • Bugs.
  • Acknwoledgements.
  • Developing log.(When)

优点(Why)

  • 源码附上一份README, 非常节省他人时间, 尽可能的避免其他开发者走弯路.
  • 待深入体会后补充

建议

  • README中提供实例展示. 有时候一个例子展示胜过千言万语.
  • 如果可以,尽量用英语编写.
  • 在一些关键词上, 考虑到不同水平人群的阅读, 应该添加上相应的WIKI链接.
  • 每行79个字符.
  • 待补充

Examples

References