Home | History | Annotate | Download | only in docguide 
      1 # README.md files
      2 
      3 About README.md files.
      4 
      5 1.  [Overview](#overview)
      6 1.  [Guidelines](#guidelines)
      7 1.  [Filename](#filename)
      8 1.  [Contents](#contents)
      9 1.  [Example](#example)
     10 
     11 ## Overview
     12 
     13 `README.md` files are Markdown files that describe a directory.
     14 GitHub and Gitiles renders it when you browse the directory.
     15 
     16 For example, the file /README.md is rendered when you view the contents of the
     17 containing directory:
     18 
     19 https://github.com/google/styleguide/tree/gh-pages
     20 
     21 Also `README.md` at `HEAD` ref is rendered by Gitiles when displaying repository
     22 index:
     23 
     24 https://gerrit.googlesource.com/gitiles/
     25 
     26 ## Guidelines
     27 
     28 **`README.md` files are intended to provide orientation for engineers browsing
     29 your code, especially first-time users.** The `README.md` is likely the first
     30 file a reader encounters when they browse a directory that
     31 contains your code. In this way, it acts as a landing page for the directory.
     32 
     33 We 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
     35 provide interfaces for other teams.
     36 
     37 ### Filename
     38 
     39 Use `README.md`.
     40 
     41 Files named `README` are not displayed in the directory view in Gitiles.
     42 
     43 ### Contents
     44 
     45 At minimum, every package-level `README.md` should include or point to the
     46 following information:
     47 
     48 1.  **What** is in this package/library and what's it used for.
     49 2.  **Who** to contact.
     50 3.  **Status**: whether this package/library is deprecated, or not for general
     51     release, etc.
     52 4.  **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 
     61 This is the top-level directory for all externally-visible APIs, plus some
     62 private APIs under `internal/` directories.
     63 See [API Style Guide](docs/apistyle.md) for more information.
     64 
     65 *TL;DR*: API definitions and configurations should be defined in `.proto` files,
     66 checked into `apis/`.
     67 
     68 ...
     69 ```
     70