如何为我的开源项目创建规范的 Readme?

开源
Hacktober 已经结束了,但这并不意味鼓励程序员为开源做贡献的结束。维护者吸引更多长期贡献者的方法之一是写一个规范的 README。

[[435194]]

Hacktober 已经结束了,但这并不意味鼓励程序员为开源做贡献的结束。维护者吸引更多长期贡献者的方法之一是写一个规范的 README。这里,参照一些流行的开源库中的 README 整理了一份清单,让你创建一个能吸引贡献者加入你的社区的 README。

Hacktoberfest 是由知名云服务商 DigitalOcean 发起的一个推广、支持开源的年度在线活动,任何一个开源爱好者都可以参与。只要在10月份内向 GitHub 上的任意开源项目提交若干 Pull Request,就算完成活动任务,并将得到由 DigitalOcean、GitHub 等活动赞助商提供的纪念品。通常是限量版T恤、贴纸若干。

那么,Hacktoberfest 这个奇怪的名字是什么意思呢?这不是一个原生的英文单词,是由几个代表着这个活动的核心精神的单词缩写组合而成。其中的 Hacktober 是由 Hackathon(黑客马拉松) 和 October(十月) fest 则是 Festival(节日)的前几个字幕。看到这里,大家应该就明白了吧, Hacktoberfest 就是开源爱好者在每年的十月份通过做开源贡献的方式来传播、庆祝开源。

我为什么要写 README?

就像找工作要写个人简历一样,为自己的开源项目写一个优秀的 README 同样重要。你README 可以为新用户和潜在贡献者提供了对我们项目的第一印象。说白了,你的 Contributing.md 可以让贡献者在你的版本库中提出和合并拉动请求,而你的 README 则指导用户如何使用你的项目。

我应该在 README 中写些什么?

首先添加项目标题

这个例子来自 Open sauce。

添加一些简短的陈述,描述项目出现原因和作用

这个例子来自Slinkity

告知用户如何安装和使用我们的项目

这个例子来自Timber

让用户知道如何获得帮助

这个例子来自RasaHQ

包括重要文档的链接

这个例子来自CodeNameOne

展示你的贡献者

这个例子来自 use-shopping-cart

添加项目的许可证

这个例子来自 use-shopping-cart

可以附加一点

  • 目录(这里有一个关于自动生成目录的文档)
  • 项目的技术堆栈和功能
  • 已经在用的产品
  • 项目的用户界面截图
  • 依赖
  • 已知的问题

怎么把它弄漂亮点

试试使用Readme.so,这是由Katherine Peterson建立的开源项目,可以轻松建立和定制README的所有部分。

 

作者:Rizel Scarlett 译者:前端小智 来源:dev 原文:https://dev.to/github/how-to-create-the-perfecreadme-for-your-open-source-project-1k69

 

责任编辑:武晓燕 来源: 大迁世界
相关推荐

2020-03-30 17:43:13

开源开源项目编写文档

2020-03-06 09:58:54

IT融资技术

2018-06-20 15:50:07

WindowsWindows 10USB

2020-02-10 19:05:46

DNS域名

2012-08-13 10:23:07

newland.js

2023-05-29 15:53:32

DevOps架构自动化

2009-05-20 13:44:35

JavaPair

2021-08-23 11:35:37

代码开发开源

2020-07-16 07:50:53

Nginx模块动态

2022-05-08 13:05:22

职位产品经理开源

2020-04-15 10:50:19

编程语言工具技术

2015-07-30 09:46:42

开源项目

2009-03-04 11:29:24

ibmdwJava

2013-10-09 09:39:17

开源

2013-12-30 17:03:20

开源开源力量

2016-10-13 14:50:26

开源代码安全

2022-08-09 11:51:49

数据存储智慧城市

2023-09-29 08:53:30

线程池java函数

2020-09-25 06:32:25

前端

2021-10-25 05:43:40

前端技术编程
点赞
收藏

51CTO技术栈公众号