Google Documentation Guide

Includes Markdown Style Guide
See docguide/README.md

docguide/README.md

@@ -0,0 +1,10 @@
+# Google documentation guide
+
+* [Markdown styleguide](style.md)
+* [Best practices](best_practices.md)
+* [README files](READMEs.md)
+* [Philosophy](philosophy.md)
+
+## See also
+
+* [How to update this guide](https://goto.google.com/doc-guide), for Googlers.

docguide/READMEs.md

@@ -0,0 +1,69 @@
+# README.md files
+
+About README.md files.
+
+1.  [Overview](#overview)
+1.  [Guidelines](#guidelines)
+1.  [Filename](#filename)
+1.  [Contents](#contents)
+1.  [Example](#example)
+
+## Overview
+
+`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:
+
+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/
+
+## Guidelines
+
+**`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.
+
+### Filename
+
+Use `README.md`.
+
+Files named `README` are not displayed in the directory view in Gitiles.
+
+### Contents
+
+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.
+
+## Example
+
+```markdown
+# 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/`.
+
+...
+```

docguide/VERSION

@@ -0,0 +1 @@
+1.0

docguide/best_practices.md

@@ -0,0 +1,115 @@
+# Documentation Best Practices
+
+"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)
+
+## Minimum viable documentation
+
+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.
+
+## Update docs with code
+
+**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.
+
+## Delete dead documentation
+
+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.
+
+## Prefer the good over the perfect
+
+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.
+
+## Documentation is the story of your code
+
+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).

docguide/philosophy.md

@@ -0,0 +1,71 @@
+# Philosophy
+
+埏埴以為器，當其無，有器之用.
+
+*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)
+
+## Radical simplicity
+
+* **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.
+
+## Readable source text
+
+* **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.
+
+## Minimum viable documentation
+
+* **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.
+
+## Better is better than perfect
+
+* **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.