如何写一个优秀的GitHub项目README文档？

今天给大家介绍一个Github上的README文档写作教程模版，该模版目前获得6634颗星星，2296Fork，相对而言，还是比较得到大家认可的。不花哨，不别出心裁，一个比较实用的，普适性的架子；所谓教科书式，不外如此。原文是英语，大神可直接看戳我查看。下面是我翻译的中文版（未完全按照原文翻译），献丑了。

项目名称

这里再写一句骚气又精准的话描述你的项目吧。

上手指南

写几句这样的话概括接下来的内容：以下指南将帮助你在本地机器上安装和运行该项目，进行开发和测试。关于如何将该项目部署到在线环境，请参考部署小节。

安装要求

列出运行该项目必须要具备的条件以及必须要安装的软件，最好给出具体的安装步骤。

1. 必须安装我
2. 我也必须安装
3. 安装我也是必须的

安装步骤

一步一步地说明怎么去搭建环境，怎么让项目跑起来。

首先你需要

1. 干这件事
2. 干那件事
3. 继续干这件事
   ......一直到完成。

最后阐述安装完成后的情况，展示下Demo

测试

解释说明一下如何运行该系统的自动测试部分。

分解为端对端测试

解释这些测试是什么以及为什么要做这些测试
1.我是个栗子
2.我也是个栗子
3.我是栗子的哥哥

代码风格测试

解释这些测试是什么以及为什么要做这些测试
1.我是个栗子
2.我也是个栗子
3.我是栗子的哥哥

部署

对以上的安装步骤进行补充说明，描述如何在在线环境中安装该项目。

使用到的框架

Dropwizard - Web框架
Maven - 依赖属性管理
ROME - 生成RSS源

贡献者

请阅读CONTRIBUTING.md 查阅为该项目做出贡献的开发者。

版本控制

该项目使用SemVer进行版本管理。您可以在repository参看当前可用版本。

作者

地球上的盐味
您也可以在贡献者名单中参看所有参与该项目的开发者。

版权说明

该项目签署了MIT 授权许可，详情请参阅 LICENSE.md

鸣谢

该项目参考了XXX的 XXX
灵感来源于XXX
感谢女友的支持和陪伴

以上。其实在实际的写作当中，也并不一定要完全跟着这个框架来，可以根据项目情况进行增删。比如稍微复杂点的项目，就要更多的纬度去说明，那么在开头就需要列出目录（Table Of Content）。另外，图片展示也是一种常用的手段，多放图片，会让你的文档更有趣味。

关于README的写作，这里还有一份非常全面的学习资源：https://github.com/matiassingers/awesome-readme，大家也可以多多参考学习。

学习资源推荐：

第一弹：超全Python学习资源整理（入门系列）

第二弹：超全Python学习资源整理（进阶系列）

Java进阶之设计模式

Scala 开发教程

Hadoop部署及管理

RabbitMQ 消息队列

Redis基础教程

Shell脚本实现打字游戏

Python3 实现色情图片识别

Python实现3D建模工具