如何写好README [英] How to write a good 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?

旁注：

作为满足 OMG这是一个很好的README！和
OMG这个README是无用的，我发布了一个链接到gnome-cups-manager的
README作为评论。该评论现在已被删除，可能是因为
链接，所以我将内容复制到此
gist 。

推荐答案

正如其他人所说，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有一个简单但很好的 README 。我在网上发现的另一个好的是GNU Make的 README

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 

---

维基百科定义为：

一个自述文件（或阅读我）文件包含有关目录或存档中的其他文件的信息，并且通常使用计算机软件进行分发。

A readme (or read me) file contains information about other files in a directory or archive and is very commonly distributed with computer software.

并列出以下内容：

• 配置说明


• 安装说明


• 操作说明


• 文件清单


• 版权和许可信息


• 分销商或程序员的联系信息


• 已知错误


• 疑难解答


• 确认


• 更改日志

• configuration instructions
• installation instructions
• operating instructions
• a file manifest
• copyright and licensing information
• contact information for the distributor or programmer
• known bugs
• troubleshooting
• credits and acknowledgements
• a changelog

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