在Github上,怎么写出教科书级别的readme

新闻 前端
很多开发者在Github上创建一个项目的时候,往往忽视了Readme的重要性,实际上,Readme文件通常是你开源项目的第一个入口点,它的作用主要有告诉人们为什么应该使用你的项目,以及如何安装和使用,一份标准化的Readme可以简化它的创建和维护。

很多开发者在Github上创建一个项目的时候,往往忽视了Readme的重要性,实际上,Readme文件通常是你开源项目的第一个入口点,它的作用主要有告诉人们为什么应该使用你的项目,以及如何安装和使用,一份标准化的Readme可以简化它的创建和维护,所以Readme值得你花时间去创建。 

在Github上,怎么写出教科书级别的readme

今天,猿妹和大家分享一个教科书般的Readme——standard-readme,目前该项目在Github上已经标星2.3K,605个Fork。(Github地址:https://github.com/RichardLitt/standard-readme)

在Github上,怎么写出教科书级别的readme

这个库包含:

  • 定义标准的Readme规范
  • 应该有一个linter来维护Readme
  • 创建标准readme的生成器
  • Badge
  • 标准Readme中的示例

标准Readme是为开源库设计的。尽管它以前用于Node和npm项目,但它也适用于其他语言的库和包管理器。

背景

项目背景就是你为什么做这个项目,动机和背景是什么。当其他开发者无需查看模块代码就可以使用你的项目时,你的文档即已完成,这意味着你可以将模块的文档化接口与内部实现分开,所以只要接口保持不变,你就可以自由更改模块内部代码。

安装

该项目需要你安装node和npm,如下:

  1. $ npm install --global standard-readme-spec  

Generator

使用Generator,请查看generator-standard-readme。该程序包中有一个全局可执行文件来运行生成器,别名为standard-readme。(Github地址:https://github.com/RichardLitt/generator-standard-readme)

Badge

如果你的Readme符合标准要求,并且你使用的是Github,那么使用Badge就会很有用,如果要以Markdown格式添加,请使用以下代码:

  1. [![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme) 

维护者

你可以直接@该项目相关的维护者,这样其他人也可以轻易联系到他

在Github上,怎么写出教科书级别的readme

贡献者

创建一个项目不容易,最后还是要感谢一下所有的贡献者。

在Github上,怎么写出教科书级别的readme

License

最后的最后你需要声明项目的开源协议,不同的开源协议的限制条件是不一样的,这就需要你自己查阅相关条款,选择一个最适合自己项目的开源协议。

在Github上,怎么写出教科书级别的readme

 

 

 

 

责任编辑:张燕妮 来源: 开源最前线
相关推荐

2020-07-14 15:10:21

Redis架构代码

2020-02-16 14:53:49

神器插件浏览Github

2015-10-15 09:53:46

SQL恢复

2015-02-03 02:43:57

2021-10-03 14:47:26

Fedora CoreGitHub Acti运行器

2013-09-10 10:20:12

数据大数据大数据应用

2024-10-28 10:50:33

2019-04-25 07:40:40

Windows操作系统功能

2020-03-24 08:32:24

vue作用域前端

2018-06-06 18:00:24

iOS苹果微软

2019-12-04 08:44:59

前后端分离开发

2017-01-15 15:20:47

Linux编程log

2024-07-22 11:48:42

2020-04-02 18:30:28

PythonGitHub编程语言

2020-04-02 16:02:44

PythonGithub博客

2019-02-26 15:23:01

数据安全磁盘

2022-06-10 11:51:49

MySQL事务隔离

2010-08-27 18:01:17

Linux Shell

2021-04-05 17:55:16

GitHub恶意软件加密货币

2020-02-27 16:17:31

代码规范codegithub
点赞
收藏

51CTO技术栈公众号