如何写一个优秀的 GitHub 项目 ReadMe 自述文档？[分享]

觉得不错的一个模板,为了更好的提升阅读效率,有必要分享下.该模版目前获得 6634 Star，2296 Fork，相对而言，还是比较得到大家认可的。不花哨，不别出心裁，一个比较实用的，普适性的架子.

分享来自实验楼官博!~~~
本文的 Github 原地址:点击这里

-------------------分割线--------------------

项目名称

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

上手指南

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

安装要求

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

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）。另外，图片展示也是一种常用的手段，适当地放图片，会让你的文档更有趣味。

我是 S7ven,在前进的路上从未止步! 请期待!