畅行 GitHub:2019年国际时事新闻怎么写一个超棒的 README 文档

文章正文
2020-07-27 23:39

如果你很发急、只是想要模板,2019年国际时事新闻可以直接跳到底部(但如许一点不酷),准备酷的人,迈出成为 README 人人的第一步吧!(绝对不是点击诱饵)

若是你方才建设了很棒的项目,并在 GitHub 上共享了它。你以为此刻你只需坐等天下汇报你这个项目有多酷。事实,在已往的一个月中,你为这个极具挑衅性的项目支付了不懈的全力,对吗?

好吧,让我们退后一步,2019国际时事新闻从搜查项目标开辟职员或者用户的角度来看。尽量你知道本身的项目有多酷,也知道它是怎样办理一个(直到你显现之前)尚未办理的紧要题目,可是看你项目标人想知道你构建了一个什么样的天下。

如果没有人知道怎样行使你的软件,那环境很是糟糕。

如果人们不知道你的软件是做什么的,就不会行使它或者为它做出孝顺,而且很也许会在开源软件的海洋中寻到更清晰明白的对象。

这就是 README 文件的用场!

好的 README 文档就像是项目标外面。这是一小我私人在你的项目中起首要看的对象,它提供了软件的简要先容。

雅观适用的 README 文档可以使你的项目脱颖而出,并引发开辟职员社区的存眷。

这将辅佐他们相识你的项目,国际时事新闻软件以及它要怎样行使、为什么他们理当做出孝顺。

“哇,店员!太棒啦!既然你知道这么多,为什么不汇报我们该怎么写……”

嘿,我不能说有一套详细的法则,你要全力服从这些法则,而不是要全力写一个好的 README。

它不是那样的。

我将分享我是如作甚我的开源项目写 README 的,以及你在为项目编写 README 文件时应思考的事项,如许你将(有但愿)收成一些看法。

GitHub 链接:https://github.com/navendu-pottekkat

其它请记着,2018国际新闻热点你不会一天之内就能干撰写 README。像全体事物一样,它必要实践。

我已经为开源孝顺一段时刻了,我留神到全体优胜的项目都有一个很棒的 README。

当你位于项目界面时,你可以几分钟之内启动并运行你的项目版本。

有许多的孝顺者、拉取哀求、频仍宣告的更新版本,都有一个很棒的 README。

新的开辟职员将可以兴许寻到全体具体信息以最先行使,譬喻安装申明和孝顺指南。

新的用户将可以兴许通过具体的屏幕截图和演示学会怎样行使该项目。

“我没时刻做这个,快给我看 README!”

好吧,好吧,2018国际时事热点汇总好吧(对不起我有点像麦康纳)。

以下是我的 NSFW 过滤项目标 README,我以为这是我写过最好的 README:https://github.com/navendu-pottekkat/nsfw-filter/blob/master/README.md

我将先容 README 的差异部门,这些部门应付每个 README 都是必不行少的。

下面是本例中行使的 README 文件的链接。你还可以寻到一个模板 README,并直接复制和粘贴到项目中:https://github.com/navendu-pottekkat/awesome-readme/tree/master

项方针题

问题应具有自我表明性,只管不要太拗口。(虽然存在破例,像本文 “超棒的开源项目 README 编写指南”会是一个很酷的名字)

为你的 README 添加一个封面或者横幅图片。为什么?由于它很轻易引发人们的留神,并且看起来很酷。

等等,我忘了一件事。你可以将此链接的 README 用作模板:https://towardsdatascience.com/media/README-template.md

横幅的最佳尺寸是 1280x650px。你还可以将其用于 repo 的交际预览。

我小我私人行使 Canva 网站建设横幅图像。全体根基内容都是免费的(在大大都环境下,2018国际时政热点新闻你没必要要专业版)。

问题下那些绮丽的对象是什么?

看起来不错吧?这些被称为徽章,它们通过提供一些快速看法进步了可读性,对吗?

你可以在你的项目中行使良多徽章,并且它们切当取决于项目。下面是我在每个项目中常用的一些。

我行使 Shields IO 网站建筑徽章。这是一种简朴易用的器材,你可以行使险些全体的徽章:https://shields.io

演示预览

写完项目后,最好对项目举办演示或者预览(视频 / gif / 屏幕截图都是不错的挑选),以便人们知道你的项目中会有什么。你也可以在上一节中的演示中添加产物申明。

这是一个随机 GIF 作为占位符。

目次

在先容了项目之后,添加目次是一个好主张。这将使人们可以更轻松地赏识你的 README,并准确寻到他们想要的内容。

这是一个示例目次(哇!太酷了!),现实上是本文的目次。

项方针题

演示预览

目次

安装

行使要领

成长

孝顺

援助

添加新成果或者修复过错

容许证

页足

安装

你也许已经留神到了返回顶部的按钮(如果没有,请留神,它就在这里!)。这是一个好主张,由于它使 README 更易于赏识。

第一个题目理当是怎样安装(怎样行使项目或者如安在古板中启动编纂)。

这里理当给用户认真的设法,并申明他们怎样行使项目 repo 的全体步调。

凭证以上步调,他们理当可以兴许在本身的设备中运行它。

我的要领是,完成 README 后,从新最先阅读这些步调并搜查是否实用。

这是一个示例指令:

要行使此项目,请起首行使以下呼吁在你的设备上克隆

git init 

git clone

GitHub 链接:https://github.com/navendu-pottekkat/nsfw-filter.git

用法

这部门是可选的,用于向用户提供安装后怎样行使项目标信息,也可以添加到 “安装”部门。

成长

在这里,你可以向开辟职员申明怎样修改代码。

你可以深刻申明代码怎样事变及全体内容怎样组合在一路。

你还可以提供怎样配置开辟情形的详细申明。

抱负环境下,你理当使 README 维持简捷。如果必要添加更伟大的申明,请行使 Wiki:https://github.com/navendu-pottekkat/nsfw-filter/wiki

孝顺

在这里,你可以让人们知道他们如作甚你的项目做出孝顺。下面给出了一些要领。

这也表现了如安在节中添加子节。

援助

你的项目备受青睐,而且已经被成千上万的人行使(有了这个 README 文件,将会有更高行使量)。此刻,是时辰探求职员或者构造来援助你的项目了。

这也许是由于你没有从项目中得到任何收入,你必要钱来保持项目留存。

你可以在此部门中添加人们怎样援助你的项目。在此处添加你的 patreon 或者 GitHub 援助商链接,以方便会面。

一个好主张是还要向援助商展现他们的构造徽标或者徽章,向他们表达你的爱!(总有一天我会寻到援助商,并向他们表达我的爱)

添加新成果或者修复过错

这是为了让人们相识如安在你的项目中提出题目或者提出成果请求。

你还可觉得项目提交、宣告或者拉取哀求提供诱导。

就小我私人和尺度而言,你理当行使一个题目模板和拉取哀求模板,以便用户打开新题目时可以凭证项目指南轻松地目录化它:https://github.com/navendu-pottekkat/nsfw-filter/blob/master/ISSUE_TEMPLATE.md

你还可以添加接洽人具体信息,以便人们就你的项目与你取得接洽。

容许证

将容许证添加到 README 是一个好风俗,如许人们可以轻松地引用它。

确保已在项目文件夹中添加了容许证文件。快捷办法:在 GitHub 中单击 repo 根目次下的添加新文件 -->将文件名配置为 LICENSE -->GitHub 表现容许证模板 --->挑选最得当项目标模板!

我小我私人添加了容许证名称,并提供了指向它的链接,如下所示:https://opensource.org/licenses/GPL-3.0

页足

我们还可以添加一个页足,由于我喜好页足,可以行使它来通报紧张信息。

让我们将其建筑为图像,由于到今朝为止你已经意识到图像中的多媒体 == 酷(* 请留神这个玄妙的编程打趣)。

就是如许…… 你已经完成了你的实习,小蚱蜢。此刻是时辰将这些设法用于你的项目了。

当你的项目与酷炫的 README 一路启动时,不要健忘 README Sensei(很酷的推特处抱负法)。

如果你以为有辅佐,请在 GitHub 上标星号并共享本指南。

此刻,你们一向在守候的时候!页足![喘息]

好吧,工作就如许竣事了。

文章评论