如何写好README

本文介绍了如何写好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的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！