今天给大家介绍一个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建模工具

如何写一个优秀的GitHub项目README文档？的更多相关文章

  1. 为Github项目创建文档

    有两种编写方式: In reStructuredText In Markdown In reStructuredText  工具:  pip install sphinx sphinx-autobui ...

  2. 优秀的github项目学习

    优秀的github项目学习 后期会陆续添加遇到的优秀项目 https://github.com/chaijunkun

  3. 喜大普奔！GitHub中文版帮助文档上线了！

    日前,GitHub 文档的简体中文正式发布,开发者可以到官方文档上随意查阅浏览中文文档啦!   对于想要玩 GitHub,但一直苦于英语水平较差的程序员来说,这真是一个天大的好消息.下面一起来感受一下 ...

  4. 手把手教你搭建一个跟vue官方同款文档（vuepress）

    前言 VuePress 由两部分组成:第一部分是一个极简静态网站生成器 (opens new window),它包含由 Vue 驱动的主题系统和插件 API,另一个部分是为书写技术文档而优化的默认主题 ...

  5. kettle开源项目部署文档

    kettle开源项目部署文档 1.kettle简介 kettle是一款国外开源的ETL(Extract Transform Load)工具,纯java编写,可以在Windows.Linux.Unix上 ...

  6. xxxx征集系统项目目标文档

    分组:每四人一组 主题:xxx征集系统 成果: 讨论结束后,每组提交一份课堂讨论记录(电子版发表到博客上,纸质版小组成员签名,下节课提交). 每人根据课堂讨论结果提交一份系统利益相关者描述案例.撰写项 ...

  7. xxx征集系统项目目标文档

    分组:每四人一组 主题:xxx征集系统 成果: 讨论结束后,每组提交一份课堂讨论记录(电子版发表到博客上,纸质版小组成员签名,下节课提交). 每人根据课堂讨论结果提交一份系统利益相关者描述案例.撰写项 ...

  8. 如何快速访问MSDN某一个类或方法的帮助文档

    如何快速访问MSDN某一个类或方法的帮助文档? 我一般都是在Google上搜索的如"string msdn",而不是在Msdn上直接查找(你不可能知道所有的类或方法的完整命名空间) ...

  9. Jenkins构建项目帮助文档

    Jenkins构建项目帮助文档 主要步骤 一.配置jdk 1.1.   下载jdk,安装到自己电脑磁盘的Java目录下(比如:D:\Java\jdk). 1.2.   Jdk环境变量的配置: 1. 鼠 ...

随机推荐

  1. python 利用tkinter模块设计出window窗口(搞笑版）

    代码如下 from tkinter import * import tkinter from tkinter import messagebox #定义了一个函数,当关闭window窗口时将会弹出一个 ...

  2. easyui combobox setValue方法不能触发onSelect事件

    //setValue方法不能触发onSelect事件 //$("#FundingSource").combobox("setValue", data.Fundi ...

  3. C# 调用存储过程 Sql Server存储过程 存储过程报错，程序中的try

    C#程序调用Sql Server存储过程,存储过程中报错情况,返回值... 0.SQL存储过程 USE [Opos] GO /****** Object: StoredProcedure [dbo]. ...

  4. invariant theory 不变量理论

    https://baike.baidu.com/item/不变量理论/9224903?fr=aladdininvariant theory 一组几何元素由 k个参数组成的向量 P1表示．若 T为某一变 ...

  5. 垃圾回收GC3种算法的衍生品 增量回收：预测和控制GC所产生的中断时间

    小结: 1.GC和程序处理的本质是无关的: 2.增量回收:预测和控制GC所产生的中断时间: 1. 分代回收 GC和程序处理的本质是无关的,因此它所消耗的时间越短越好.分代回收的目的,正是为了在程序 运 ...

  6. nginx-upstream-bio/nio/netty-zuul2-apigateway-openresty-orange-lua-docker

    upstream_addr等到走了一些弯路,才发现nginx的upstream本来就有一个upstream_addr的模块,一下子我觉得找到了方向,不过看这个变量的说明,发现它主要用在记录log上面, ...

  7. iOS-静态库，动态库，framework，bundle浅析(四)

    1. 创建bundle,如图,点击 +  ,弹出选择框, macOS 下的Framework & Library  ,点击bundle,输入bundle的名字,然后点击 finish.   图 ...

  8. Java之旅_面向对象_多态

    参考并摘自:http://www.runoob.com/java/java-polymorphism.html 多态 多态是一个行为具有多个不同表现形式的能力. 多态就是同一个接口,使用不同的实例而执 ...

  9. scapy 中的ARP

    scapy 常用命令 ls() //查看支持的协议对象lsc() //查看函数show() //查看数据包结构send() //三层发包sr() //三层收发sr1() //三层收发只收一 timeo ...

  10. Nor Flash 驱动框架

    框架入口源文件: lcd.c (可根据入口源文件,再按着框架到内核走一遍) 内核版本:linux_2.6.22.6      硬件平台:JZ2440 以下是驱动框架: 以下是驱动代码 s3c_nor_ ...