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

作者 : 开心源码 本文共1121个字,预计阅读时间需要3分钟 发布时间: 2022-05-12 共227人阅读

今天给大家详情一个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的写作,这里还有一份非常全面的学习资源: matiassingers/awesome-readme,大家也可以多多参考学习。

学习资源推荐:

第一弹:超全Python学习资源整理(入门系列)

第二弹:超全Python学习资源整理(进阶系列)

Java进阶之设计模式

Scala 开发教程

Hadoop部署及管理

RabbitMQ 消息队列

Redis基础教程

Shell脚本实现打字游戏

Python3 实现色情图片识别

Python实现3D建模工具

说明
1. 本站所有资源来源于用户上传和网络,如有侵权请邮件联系站长!
2. 分享目的仅供大家学习和交流,您必须在下载后24小时内删除!
3. 不得使用于非法商业用途,不得违反国家法律。否则后果自负!
4. 本站提供的源码、模板、插件等等其他资源,都不包含技术服务请大家谅解!
5. 如有链接无法下载、失效或广告,请联系管理员处理!
6. 本站资源售价只是摆设,本站源码仅提供给会员学习使用!
7. 如遇到加密压缩包,请使用360解压,如遇到无法解压的请联系管理员
开心源码网 » 如何写一个优秀的GitHub项目README文档?

发表回复