如何写好github readme 怎么写中的readme

来源：蜘蛛抓取(WebSpider) 时间：2016-12-02 05:25 标签： github readme 格式
github readme 格式-学网
github readme 格式
状态:1个回答日期：支持markdown语法的。 「由一个或多个连续的文本行组成」这句话其实暗示了 Markdown 允许段落内的强迫换行(插入换行符),这个特性和其他大部分的 text-to-HTML 格式不...状态:1个回答日期：好的readme,如何才算好,一定要有高逼格,好吧,中文不够国际化,一定要有英文版本 首先logo很重要放在最上面,如meolu/walle-web ? GitHub,然后起一个最耍帅的名字,如meolu...状态:1个回答日期：一个完整的readme,应当包括一下几个部分: 首先是自述,对自己的项目进行简洁全面的概述,包括项目来源,项目主要内容,各个部分功能,项目完成主要针对的目标。 其次,要在re...状态:1个回答日期：应当包括一下几个部分: 1、首先是自述,对自己的项目进行简洁全面的概述,包括项目来源,项目主要内容,各个部分功能,项目完成主要针对的目标。 2、其次,要在readme中添加...状态:1个回答日期： git diff 对比文件的差异 git branch 列出所有分支 git log 显示提交记录 分支 git brach 分支名 创建分支 git checkout 分支名 切换分支 提交 git add 跟踪新文件或者已有文件的...状态:1个回答日期： 因为兼容html也可以直接 空格两个以上 回车! 希望我的回答对你有所帮助,如果满意请设置为最佳答案,谢谢状态:1个回答日期：这个不是由你填写的,是GITHUB通过你所做的项目中代码比例来确定的,属于自动生成的信息,理论上改不了。 不过如果你想改成你想要到信息,可以试试去建一个项目,里面用你...状态:1个回答日期：你没有必要纠结整体的意思,但是你有必要知道这段历史。 github这个词应该分开。 git:早年Torvalds 为linux 源代码做的分布式版本控制系统。 hub:中心的意思。 github:GitHub...状态:1个回答日期：首先:看 README.md ,好多项目都有,有没有说明。 其次:看 你下载的属于什么代码,对应到相应的开发环境上。 然后:就是在对应的开发环境中编译(脚本语言直接放在应用中)。...状态:1个回答日期： 重新下载,可能是未下载完全
与【github readme 格式】相关信息:&&&&&&&&&&&&&&&&&&
用户还关注
12345678910
大类导航： |热门推荐：
　　大家平时下载安装组件的时候，不知道有没有他们的组件说明文档是怎么写的吗？有的会写的很清晰明了，有的会越看越迷糊，所以开源组件的README就显得很重要了。今天的文章来自@lakb248的翻译分享。
　　正文从这开始～
　　一个项目的README是非常重要的；别人看到你的开源项目的时候第一个看到的就是README，同时README也常常是项目唯一的文档。你的README对于你的项目来说，就相当于一个公司的官方网站一样，就像网站需要注意很多用户体验一样，我们的README也应该从用户的角度出发。
　　这篇文章将告诉我们如何写一个友好的README-不论对于新手还是对你项目很了解的人来说，这个README都会非常有帮助同时可以满足开发者的需求。
　　我们会利用一个叫做&Paddington&的虚拟的库作为例子，分部分来讲解这些东西。让我们从头开始吧。
　　项目标题
　　毫无疑问，一个网站最上面一部分应该用来展示最重要的信息。我们可以把这个原则放在我们的README上。
　　所以什么才是最重要的东西呢？正如所起到的作用一样，项目名字是很重要的。所以我们先加上下面这些内容：
　　上面这个基本可以满足新用户的需求，但是README的头部也需要满足已存在的用户的需求，他们有一些很容易回答的问题。当我访问一个我很熟悉的项目的时候，我会想知道：
最新的版本的多少？
它构建通过了吗？
　　作为一个新用户，我也有一些容易回答的问题：
它是用什么语言写的？
它支持哪个语言版本？
它是否通过测试？
它采用哪种开源证书？
　　我们可以通过徽章来回答上面所有的问题！
　　我在项目描述下面加了一行徽章，单独一行不会占据很大的空间同时又能涵盖许多信息：
　　是不是很好看？我使用了一个叫做shields.io的服务，它提供了一致的徽章图标同时也提供了一个添加自定义徽章的方式，比如开源证书信息。
　　对于头部的最后一部分，如果项目足够简单的话，我们可以添加一个简单的例子。这对于新手理解你的项目是用来干什么的有很大帮助，就像项目描述一样。
　　我们在头部有限的空间里面涵盖了丰富的内容。好极了！现在我们需要看看一些更具体的问题。如果我们的README会变得很长，那么要导航到某个具体的内容就变得很困难，现在添加一个目录就变得很有意义。
　　目录对于相对比较短的README来说也是很有用的。它解决了信息索引的需求，为用户提供了一些有帮助的跳转链接到文档的不同部分。
　　如果用户只想要看看使用说明，为什么要让他们滚动页面看到他并不需要的安装指南呢，更何况安装指南只有第一次使用项目的时候会用到。
　　必要条件
　　现在我们来到文档中对于新用户更有用的部分，我们要确保他们获取他们所需要的信息。这部分就是用来添加所有你项目的必要条件的地方：语言，语言版本，包管理工具，操作系统。
　　这些内容可以直接写上去或者通过列表来展示，明显列表更清晰一些。这对你来说也很有用，这可以帮你有效的减少因为缺少必要条件而提交的ISSUE的数量。
　　在写必要条件的时候，你应该假设从0基础开始使用你的项目。确保你添加了语言和包管理工具的相关链接，这样你也许能帮助到对于项目一无所知的新手。
　　你的使用手册可能是你README中最重要的部分，如果没有这个很少人可以知道怎么用你的项目。
　　这部分可以用很多种方式来写，这取决于你项目的类型。你也许需要一个API手册，一个web接口或者一个命令行工具；有时需要不只一种。下面这个手册涉及到一个Java API，不过你可以把这个方式应用到其他的接口文档上。
　　首先我们需要提到如何获取代码，是通过clone代码还是利用包管理工具来安装。别忘了添加一些有用的链接，来提供一些便利。
　　当给一个API写文档的时候，尽量保持简单清晰。也就是说先写出接口的主要用例。这可以吸引第一次看的用户。在这个例子中，我们突出了方法的参数和返回类型，并附上的例子。越明确，就能给你减少越多的麻烦。
　　我们已经涵盖了我们的主要用例，同时指明一些边界用例以及用户在使用过程中会遇到的问题也是很有帮助的。这个可以作为使用手册的子章节放在使用手册的最后。试着包括一些有问题的用户会搜索的关键词。
　　这部分也是很重要的，这决定了是否会有用户来给你贡献代码。就算你有一个CONTRIBUTING文件，如果一个人没有Github或者开源的经验就很难找到它。这部分应该包括基本信息并且如果你有一个CONTRIBUTING文件应该加上一个链接。
　　增加一个关于如何运行测试和提交pull request的简单介绍，对你来说也很有用。这意味着你review pull request的过程会更加有效率。
　　支持和版本变化
　　一个关于项目支持状态的章节也是很有用的，特别是当你发布了很多个不同的主版本的时候。这部分对于一些要进行版本迁移的老用户来说非常有帮助。
　　一个完整的迁移指南对于README来说可能太长了，所以我在项目中加入了一个MIGRATION文件，同时在README中添加了链接。
　　如果你有一个对于老版本的支持计划，请突出他们。同时你也可以用一个简单的表格来列出主要的版本和他们支持的最后期限。
　　最后你应该加一个版权信息以及一个项目所使用开源证书的链接。如果没有这些信息很多用户无法使用你的项目，特别是一些大企业。就算你的项目里面有一个LICENSE文件，添加一个证书的链接也是很有用的。
　　其他部分
　　我们上面介绍的内容并没有包括了README可以写的全部内容。我项目中还包括了其他内容包括：
　　如果你的项目做了一些其他项目已经做了的事情，或者特别复杂，提供一些解释也是很有帮助的。
共有的问题
　　一个用来列出经常出现的问题的地方，可以减少重复打开的ISSUE。
　　一个指向例子的链接。
　　一个关于项目变更日志的描述。
　　一个完整的 README
　　现在我们已经拥有一个友好的README，你可以在这里看到所有内容。
　　我希望更多的人在写文档的时候可以考虑用户的需求，如果你觉得漏了什么请告诉我。我对于如何写好README的建议和想法很感兴趣。
　　关于本文
　　译者：@lakb248
　　译文链接：http://bin-playground.top/#/blog//writing-a-friendly-readme/
　　原文链接：/posts/writing-a-friendly-readme/
　　欢迎投稿到前端早读课
投稿邮箱：
请先登录再操作
请先登录再操作
微信扫一扫分享至朋友圈
知名IT评论人，曾就职于多家知名IT企业，现是科幻星系创建人
未来在这里发声。
新媒体的实践者、研究者和批判者。
立足终端领域，静观科技变化。深入思考，简单陈述。
智能硬件领域第一自媒体。你的浏览器禁用了JavaScript, 请开启后刷新浏览器获得更好的体验!
没接触过markdown，百度上的资料在github上好像行不通。求教！
要回复问题请先或
浏览: 1155
关注: 2 人

我要回帖

更多关于 github readme 格式 的文章

 

随机推荐