README文件：目的、位置和内容

README

自述文件是目录内容的简短摘要。查看包含目录的内容时，文件的内容会显示在GitHub和Gitiles中。README文件为浏览代码的用户（尤其是首次使用的用户）提供关键信息。

本文档介绍了如何创建可通过markdown读取的README文件。

可读自述文件

README文件必须命名 README.md. 文件名 必须 结尾是 .md 扩展名，区分大小写。

例如，当您查看包含目录的内容时，将呈现文件/README.md ：

https://github.com/google/styleguide/tree/gh-pages

也有 README.md 于 HEAD ref由Gitiles在显示仓库索引时渲染：

https://gerrit.googlesource.com/gitiles/

将自述文件放在哪里

与所有其他Markdown文件不同， README.md 文件不应位于您的产品或库的文档目录中。 README.md 文件应位于产品或库的实际代码库的顶级目录中。

代码包的所有顶级目录都应具有最新的 README.md 文件。这对于为其他团队提供接口的包目录尤其重要。

在自述文件中应放入哪些内容

至少，您的 README.md 文件应包含指向用户和/或团队文档的链接。

每个包级别 README.md 应包括或指向以下信息：

1. 此包或库中的内容及其用途。
2. 联络点
3. 此包或库是否被弃用的状态，是否适用于常规版本等。
4. 如何使用包或库。示例包括示例代码，可复制 bazel 命令等。
5. 相关文件的链接。

---

来源与许可

原文：Google documentation guide

归属：Google, google/styleguide contributors; documentation from the Google styleguide repository

许可：CC BY 3.0 Unported