* [Markdown styleguide](style.md)

* [Best practices](best_practices.md)

* [README files](READMEs.md)

* [Philosophy](philosophy.md)

* [How to update this guide](https://goto.google.com/doc-guide), for Googlers.

About README.md files.

1. [Overview](#overview)

1. [Guidelines](#guidelines)

1. [Filename](#filename)

1. [Contents](#contents)

1. [Example](#example)

`README.md` files are Markdown files that describe a directory.

GitHub and Gitiles renders it when you browse the directory.

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

containing directory:

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

index:

**`README.md` files are intended to provide orientation for engineers browsing

your code, especially first-time users.** The `README.md` is likely the first

file a reader encounters when they browse a directory that

contains your code. In this way, it acts as a landing page for the directory.

We recommend that top-level directories for your code have an up-to-date

`README.md` file. This is especially important for package directories that

provide interfaces for other teams.

Use `README.md`.

Files named `README` are not displayed in the directory view in Gitiles.

At minimum, every package-level `README.md` should include or point to the

following information:

1. **What** is in this package/library and what's it used for.

2. **Who** to contact.

3. **Status**: whether this package/library is deprecated, or not for general

release, etc.

4. **More info**: where to go for more detailed documentation, such as:

* An overview.md file for more detailed conceptual information.

* Any API documentation for using this package/library.

# APIs

This is the top-level directory for all externally-visible APIs, plus some

private APIs under `internal/` directories.

See [API Style Guide](docs/apistyle.md) for more information.

*TL;DR*: API definitions and configurations should be defined in `.proto` files,

checked into `apis/`.

...

1.0

"Say what you mean, simply and directly." - [Brian Kernighan]

(http://en.wikipedia.org/wiki/The_Elements_of_Programming_Style)

Contents:

1. [Minimum viable documentation](#minimum-viable-documentation)

1. [Update docs with code](#update-docs-with-code)

1. [Delete dead documentation](#delete-dead-documentation)

1. [Documentation is the story of your code](#documentation-is-the-story-of-your-code)

A small set of fresh and accurate docs are better than a sprawling, loose

assembly of "documentation" in various states of disrepair.

Write short and useful documents. Cut out everything unnecessary, while also

making a habit of continually massaging and improving every doc to suit your

changing needs. **Docs work best when they are alive but frequently trimmed,

like a bonsai tree**.

This guide encourages engineers to take ownership of their docs and keep

them up to date with the same zeal we keep our tests in good order. Strive for

this.

* Identify what you really need: release docs, API docs, testing guidelines.

* Delete cruft frequently and in small batches.

**Change your documentation in the same CL as the code change**. This keeps your

docs fresh, and is also a good place to explain to your reviewer what you're

doing.

A good reviewer can at least insist that docstrings, header files, README.md

files, and any other docs get updated alongside the CL.

Dead docs are bad. They misinform, they slow down, they incite despair in

engineers and laziness in team leads. They set a precedent for leaving behind

messes in a code base. If your home is clean, most guests will be clean without

being asked.

Just like any big cleaning project, **it's easy to be overwhelmed**. If your

docs are in bad shape:

* Take it slow, doc health is a gradual accumulation.

* First delete what you're certain is wrong, ignore what's unclear.

* Get your whole team involved. Devote time to quickly scan every doc and make

a simple decision: Keep or delete?

* Default to delete or leave behind if migrating. Stragglers can always be

recovered.

* Iterate.

Your documentation should be as good as possible within a reasonable time frame.

The standards for an documentation review are different from the

standards for code reviews. Reviewers can and should ask for improvements, but

in general, the author should always be able to invoke the "Good Over Perfect

Rule". It's preferable to allow authors to quickly submit changes that improve

the document, instead of forcing rounds of review until it's "perfect". Docs are

never perfect, and tend to gradually improve as the team learns what they really

need to write down.

Writing excellent code doesn't end when your code compiles or even if your

test coverage reaches 100%. It's easy to write something a computer understands,

it's much harder to write something both a human and a computer understand. Your

mission as a Code Health-conscious engineer is to **write for humans first,

computers second.** Documentation is an important part of this skill.

There's a spectrum of engineering documentation that ranges from terse comments

to detailed prose:

1. **Inline comments**: The primary purpose of inline comments is to provide

information that the code itself cannot contain, such as why the code is

there.

2. **Method and class comments**:

* **Method API documentation**: The header / Javadoc / docstring

comments that say what methods do and how to use them. This

documentation is **the contract of how your code must behave**. The

intended audience is future programmers who will use and modify your

code.

It is often reasonable to say that any behavior documented here should

have a test verifying it. This documentation details what arguments the

method takes, what it returns, any "gotchas" or restrictions, and what

exceptions it can throw or errors it can return. It does not usually

explain why code behaves a particular way unless that's relevant to a

developer's understanding of how to use the method. "Why" explanations

are for inline comments. Think in practical terms when writing method

documentation: "This is a hammer. You use it to pound nails."

* **Class / Module API documentation**: The header / Javadoc / docstring

comments for a class or a whole file. This documentation gives a brief

overview of what the class / file does and often gives a few short

examples of how you might use the class / file.

Examples are particularly relevant when there's several distinct ways to

use the class (some advanced, some simple). Always list the simplest

use case first.

3. **README.md**: A good README.md orients the new user to the directory and

points to more detailed explanation and user guides:

* What is this directory intended to hold?

* Which files should the developer look at first? Are some files an API?

* Who maintains this directory and where I can learn more?

See the [README.md guidelines](READMEs.md).

埏埴以為器，當其無，有器之用.

*Clay becomes pottery through craft, but it's the emptiness that makes a pot

useful.*

\- [Laozi](http://ctext.org/dictionary.pl?if=en&id=11602)

Contents:

1. [Radical simplicity](#radical-simplicity)

1. [Readable source text](#readable-source-text)

1. [Minimum viable documentation](#minimum-viable-documentation)

1. [Better is better than perfect](#better-is-better-than-perfect)

* **Scalability and interoperability** are more important than a menagerie of

unessential features. Scale comes from simplicity, speed, and ease.

Interoperability comes from unadorned, digestable content.

* **Fewer distractions** make for better writing and more productive reading.

* **New features should never interfere with the simplest use case** and should

remain invisible to users who don't need them.

* **This guide is designed for the average engineer** -- the busy,

just-want-to-go-back-to-coding engineer. Large and complex documentation is

possible but not the primary focus.

* **Minimizing context switching makes people happier.** Engineers should be

able to interact with documentation using the same tools they use to read and

write code.

* **Plain text not only suffices, it is superior**. Markdown itself is not

essential to this formula, but it is the best and most widely supported

solution right now. HTML is generally not encouraged.

* **Content and presentation should not mingle**. It should always be possible

to ditch the renderer and read the essential information at source. Users

should never have to touch the presentation layer if they don't want to.

* **Portability and future-proofing leave room for the unimagined integrations

to come**, and are best achieved by keeping the source as human-readable as

possible.

* **Static content is better than dynamic**, because content should not depend

on the features of any one server. However, **fresh is better than stale**. We

strive to balance these needs.

* **Docs thrive when they're treated like tests**: a necessary chore one learns

to savor because it rewards over time.

See [Best Practices](best_practices.md).

* **Brief and utilitarian is better than long and exhaustive**. The vast

majority of users need only a small fraction of the author's total knowledge,

but they need it quickly and often.

* **Incremental improvement is better than prolonged debate**. Patience and

tolerance of imperfection allow projects to evolve organically.

* **Don't lick the cookie, pass the plate**. We're drowning in potentially

impactful projects. Choose only those you can really handle and release those

you can't.