本文介绍了如何写好README的处理方法,对大家解决问题具有一定的参考价值,需要的朋友们下面随着小编来一起学习吧!

问题描述

我猜每个人都看过一个 README 文件,但是我想要如何编写一个很好的 README 文件中花费最少的精力。

I guess everyone has seen a README file, but I would like the definitive guide on how to write an excellent README file with the least amount of energy spent on it.


  • 什么是 README 文件?

  • 我应该写什么?

  • 我应该如何格式化?

  • What's a README file?
  • What should I write in it?
  • How exactly should I format it?

旁注


推荐答案

正如其他人所说,README应该简单而简短,一个很好的README可以节省时间,特别是如果它是像命令行参数解析库。

As others have noted, README should be simple and short, but a good README can save time especially if it's for something like command-line parameter parsing library.

这是我认为应该包括:


  • 项目名称和所有子模块和库(有时它们被命名不同,对新用户非常混乱)

  • 描述的所有项目,以及所有子模块和库

  • 5行代码片段如何使用(如果是图书馆)

  • 版权和许可信息(或阅读许可证)

  • 指示,以获取文档

  • 说明来安装,配置和运行程序

  • 指示g rab最新的代码和详细的说明来构建它(或快速概述和阅读INSTALL)

  • 作者列表或阅读作者

  • 指示提交错误,功能请求,提交修补程序,加入邮件列表,获取公告或以其他形式加入用户或开发社区

  • 其他联系信息(电子邮件地址,网站,公司名称,地址等)

  • 简短的历史,如果它是替换或叉子的其他东西

  • 法律通知(密码)

  • name of the projects and all sub-modules and libraries (sometimes they are named different and very confusing to new users)
  • descriptions of all the project, and all sub-modules and libraries
  • 5-line code snippet on how its used (if it's a library)
  • copyright and licensing information (or "Read LICENSE")
  • instruction to grab the documentation
  • instructions to install, configure, and to run the programs
  • instruction to grab the latest code and detailed instructions to build it (or quick overview and "Read INSTALL")
  • list of authors or "Read AUTHORS"
  • instructions to submit bugs, feature requests, submit patches, join mailing list, get announcements, or join the user or dev community in other forms
  • other contact info (email address, website, company name, address, etc)
  • a brief history if it's a replacement or a fork of something else
  • legal notices (crypto stuff)

Apache HTTP Server有一个简单但很好的。我在网上发现的另一个好的是GNU Make的

Apache HTTP Server has a simple yet good README. Another good one I found available online is GNU Make's README.

根据格式,我会尽可能地坚持Unix传统,和/或使用markdown,特别是github项目,将README.md作为HTML 。

As per formatting, I would say stick to the Unix traditions as much as possible, and/or use markdown especially for github projects, which renders README.md as html.


  • 只有ASCII文字,如果README用英文写成

  • 用英文写成可能和船舶翻译版本与双字母语言代码扩展名README.ja

  • 每行80个字符或更少字符

  • 段落之间的单个空行

  • 标题下的短划线

  • 使用空格缩进(0x20)不是标签

  • ASCII characters only, if the README is written in English
  • write it in English if possible, and ship translated version with two-letter language code extension like README.ja
  • 80 characters or less per line
  • single empty line between paragraphs
  • dashes under the headers
  • indent using whitespace (0x20) not tab

把它们放在一起...

Putting it all together...

Documentation
-------------

GNU make is fully documented in the GNU Make manual, which is contained
in this distribution as the file make.texinfo.  You can also find
on-line and preformatted (PostScript and DVI) versions at the FSF's web
site.  There is information there about ordering hardcopy documentation.

  http://www.gnu.org/
  http://www.gnu.org/doc/doc.html
  http://www.gnu.org/manual/manual.html 






定义为:

并列出以下内容:

这篇关于如何写好README的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持!

10-30 01:41