如何让你的Github项目撰写出色的README文件

百度已收录   阅读次数: 587
2021-05-2100:20:00 发表评论
摘要

如果您使用的是GitHub,则意味着您需要为您的项目编写好的文档,以帮助其他人理解它们。老实说,当我开始在Github上推送项目时,我什至不知道什么是README文件(即使我在其他人的项目中也可以看到它),直到伯衡君看了更多人的项目后,都发现一个共同点,都有一个叫做README的文件,才知道它的作用原来是说明项目之意,于是就想如何写得好看,通俗易通而且美观,参考了众多资料后,可以这样操作……

如何让你的Github项目撰写出色的README文件

开篇寄语

如果您使用的是GitHub,则意味着您需要为您的项目编写好的文档,以帮助其他人理解它们。老实说,当我开始在Github上推送项目时,我什至不知道什么是README文件(即使我在其他人的项目中也可以看到它),直到伯衡君看了更多人的项目后,都发现一个共同点,都有一个叫做README的文件,才知道它的作用原来是说明项目之意,于是就想如何写得好看,通俗易通而且美观,参考了众多资料后,可以这样操作……

内容详情

1.为什么需要README文件?

  • 好的自述文件可以帮助您的项目在众多其他项目中脱颖而出,它应该和项目本身一样好。
  • 这是一个人遇到您的项目时会看到的第一个文件,因此它应该简短而详细。
  • 它将帮助您专注于项目需要交付的内容以及交付方式。

2.我们开始创建它吧!

没有一种正确的方法来构建好的自述文件。但是有一种非常错误的方法,那就是根本不包含自述文件。

这些步骤是我发现的最佳实践之一。随着您事业的发展,您将对什么是好的自述文件以及如何改进自述文件有自己的见解。

自述文件需要回答以下内容,是什么以及怎么做:

  • 你的动机是什么?
  • 你为什么建立这个项目?
  • 它解决什么问题?
  • 你学到了什么?
  • 是什么使您的项目脱颖而出?如果您的项目具有很多功能,请考虑添加“功能”部分并在此处列出。

包含以下内容:

  • 项目标题,这是项目的名称,它用一句话描述了整个项目,并帮助人们理解了项目的主要目的和目的。
  • 撰写说明,您的描述是项目中极为重要的方面。精心设计的描述可让您向其他开发人员以及潜在的雇主展示您的工作。这是许多新开发人员经常忽略的项目的重要组成部分。自述文件的质量通常会将好项目与坏项目区分开。一个懂得利用这个机会的人可以来解释和展示:
    • 应用程序做什么
    • 为什么要所使用的技术
    • 您面临的一些挑战和希望将来实现的功能
  • 添加目录,如果您的自述文件很长,则可能需要添加目录以使用户轻松找到所需内容。它可以帮助他们导航到文件的不同部分
  • 如何安装,如果您的项目是需要安装的软件或应用程序,则应包括安装项目所需的步骤。提供有关如何使开发环境运行的分步说明
  • 如何使用,提供说明和示例,以便用户/贡献者可以使用该项目。如果他们遇到问题,这将使他们很容易–他们将始终有一个参考的地方
  • 列出遵从的开源协议,这是大多数自述文件的最后一部分。它使其他开发人员知道他们可以和不能对您的项目进行的操作。如果您在选择许可证方面需要帮助,请使用https://choosealicense.com/

上面列出的部分是良好自述文件的最低要求。但是您可能还需要考虑添加以下部分:

  • 徽章
如何让你的Github项目撰写出色的README文件

徽章不是必需的,但是使用徽章只是让其他开发人员知道自己在做什么的一种简单方法。

不知道从哪里得到它们?可以使用shields.io托管的徽章。

  • 测试

为您的应用程序编写测试,然后提供代码示例以及如何运行它们。

这些是编写自述文件所需的主要步骤!现在,我们已经完成了所有步骤,我相信您已经准备好将自述文件添加到您的项目中,以使它们脱颖而出。

分享至:
  • 我的微信
  • 微信扫一扫加好友
  • weinxin
  • 我的微信公众号
  • 扫描关注公众号
  • weinxin

发表评论

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen: