1*8c35d5eeSXin Li# README.md files 2*8c35d5eeSXin Li 3*8c35d5eeSXin LiAbout README.md files. 4*8c35d5eeSXin Li 5*8c35d5eeSXin Li1. [Overview](#overview) 6*8c35d5eeSXin Li1. [Guidelines](#guidelines) 7*8c35d5eeSXin Li1. [Filename](#filename) 8*8c35d5eeSXin Li1. [Contents](#contents) 9*8c35d5eeSXin Li1. [Example](#example) 10*8c35d5eeSXin Li 11*8c35d5eeSXin Li## Overview 12*8c35d5eeSXin Li 13*8c35d5eeSXin Li`README.md` files are Markdown files that describe a directory. 14*8c35d5eeSXin LiGitHub and Gitiles renders it when you browse the directory. 15*8c35d5eeSXin Li 16*8c35d5eeSXin LiFor example, the file /README.md is rendered when you view the contents of the 17*8c35d5eeSXin Licontaining directory: 18*8c35d5eeSXin Li 19*8c35d5eeSXin Lihttps://github.com/google/styleguide/tree/gh-pages 20*8c35d5eeSXin Li 21*8c35d5eeSXin LiAlso `README.md` at `HEAD` ref is rendered by Gitiles when displaying repository 22*8c35d5eeSXin Liindex: 23*8c35d5eeSXin Li 24*8c35d5eeSXin Lihttps://gerrit.googlesource.com/gitiles/ 25*8c35d5eeSXin Li 26*8c35d5eeSXin Li## Guidelines 27*8c35d5eeSXin Li 28*8c35d5eeSXin Li**`README.md` files are intended to provide orientation for engineers browsing 29*8c35d5eeSXin Liyour code, especially first-time users.** The `README.md` is likely the first 30*8c35d5eeSXin Lifile a reader encounters when they browse a directory that 31*8c35d5eeSXin Licontains your code. In this way, it acts as a landing page for the directory. 32*8c35d5eeSXin Li 33*8c35d5eeSXin LiWe recommend that top-level directories for your code have an up-to-date 34*8c35d5eeSXin Li`README.md` file. This is especially important for package directories that 35*8c35d5eeSXin Liprovide interfaces for other teams. 36*8c35d5eeSXin Li 37*8c35d5eeSXin Li### Filename 38*8c35d5eeSXin Li 39*8c35d5eeSXin LiUse `README.md`. 40*8c35d5eeSXin Li 41*8c35d5eeSXin LiFiles named `README` are not displayed in the directory view in Gitiles. 42*8c35d5eeSXin Li 43*8c35d5eeSXin Li### Contents 44*8c35d5eeSXin Li 45*8c35d5eeSXin LiAt minimum, every package-level `README.md` should include or point to the 46*8c35d5eeSXin Lifollowing information: 47*8c35d5eeSXin Li 48*8c35d5eeSXin Li1. **What** is in this package/library and what's it used for. 49*8c35d5eeSXin Li2. **Who** to contact. 50*8c35d5eeSXin Li3. **Status**: whether this package/library is deprecated, or not for general 51*8c35d5eeSXin Li release, etc. 52*8c35d5eeSXin Li4. **More info**: where to go for more detailed documentation, such as: 53*8c35d5eeSXin Li * An overview.md file for more detailed conceptual information. 54*8c35d5eeSXin Li * Any API documentation for using this package/library. 55*8c35d5eeSXin Li 56*8c35d5eeSXin Li## Example 57*8c35d5eeSXin Li 58*8c35d5eeSXin Li```markdown 59*8c35d5eeSXin Li# APIs 60*8c35d5eeSXin Li 61*8c35d5eeSXin LiThis is the top-level directory for all externally-visible APIs, plus some 62*8c35d5eeSXin Liprivate APIs under `internal/` directories. 63*8c35d5eeSXin LiSee [API Style Guide](docs/apistyle.md) for more information. 64*8c35d5eeSXin Li 65*8c35d5eeSXin Li*TL;DR*: API definitions and configurations should be defined in `.proto` files, 66*8c35d5eeSXin Lichecked into `apis/`. 67*8c35d5eeSXin Li 68*8c35d5eeSXin Li... 69*8c35d5eeSXin Li``` 70