styleguide/docguide/READMEs.md

READMEs

About README.md files.

1. Overview
2. Readable README files
3. Where to put your README
4. What to put in your README

Overview

A README is a short summary of the contents of a directory. The contents of the file are displayed in GitHub and Gitiles when you view the contents of the containing directory. README files provide critical information for people browsing your code, especially first-time users.

This document covers how to create README files that are readable with GitHub and Gitiles.

Readable README files

README files must be named README.md. The file name must end with the .md extension and is case sensitive.

For example, the file /README.md is rendered when you view the contents of the containing directory:

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

Also README.md at HEAD ref is rendered by Gitiles when displaying repository index:

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

Where to put your README

Unlike all other Markdown files, README.md files should not be located inside your product or library's documentation directory. README.md files should be located in the top-level directory for your product or library's actual codebase.

All top-level directories for a code package should have an up-to-date README.md file. This is especially important for package directories that provide interfaces for other teams.

What to put in your README

At a minimum, your README.md file should contain a link to your user- and/or team-facing documentation.

Every package-level README.md should include or point to the following information:

1. What is in this package or library and what's it used for.
2. Points of contact.
3. Status of whether this package or library is deprecated, or not for general release, etc.
4. How to use the package or library. Examples include sample code, copyable bazel run or bazel test commands, etc.
5. Links to relevant documentation.