READMEs.md
1# README.md files
2
3About README.md files.
4
51. [Overview](#overview)
61. [Guidelines](#guidelines)
71. [Filename](#filename)
81. [Contents](#contents)
91. [Example](#example)
10
11## Overview
12
13`README.md` files are Markdown files that describe a directory.
14GitHub and Gitiles renders it when you browse the directory.
15
16For example, the file /README.md is rendered when you view the contents of the
17containing directory:
18
19https://github.com/google/styleguide/tree/gh-pages
20
21Also `README.md` at `HEAD` ref is rendered by Gitiles when displaying repository
22index:
23
24https://gerrit.googlesource.com/gitiles/
25
26## Guidelines
27
28**`README.md` files are intended to provide orientation for engineers browsing
29your code, especially first-time users.** The `README.md` is likely the first
30file a reader encounters when they browse a directory that
31contains your code. In this way, it acts as a landing page for the directory.
32
33We recommend that top-level directories for your code have an up-to-date
34`README.md` file. This is especially important for package directories that
35provide interfaces for other teams.
36
37### Filename
38
39Use `README.md`.
40
41Files named `README` are not displayed in the directory view in Gitiles.
42
43### Contents
44
45At minimum, every package-level `README.md` should include or point to the
46following information:
47
481. **What** is in this package/library and what's it used for.
492. **Who** to contact.
503. **Status**: whether this package/library is deprecated, or not for general
51 release, etc.
524. **More info**: where to go for more detailed documentation, such as:
53 * An overview.md file for more detailed conceptual information.
54 * Any API documentation for using this package/library.
55
56## Example
57
58```markdown
59# APIs
60
61This is the top-level directory for all externally-visible APIs, plus some
62private APIs under `internal/` directories.
63See [API Style Guide](docs/apistyle.md) for more information.
64
65*TL;DR*: API definitions and configurations should be defined in `.proto` files,
66checked into `apis/`.
67
68...
69```
70