docguide: pull in updates from internal docs

docguide/READMEs.md

@@ -1,17 +1,26 @@
-# README.md files
+# READMEs
 
 About README.md files.
 
 1.  [Overview](#overview)
-1.  [Guidelines](#guidelines)
-1.  [Filename](#filename)
-1.  [Contents](#contents)
-1.  [Example](#example)
+1.  [Readable README files](#readable-readme-files)
+1.  [Where to put your README](#where-to-put-your-readme)
+1.  [What to put in your README](#what-to-put-in-your-readme)
 
 ## Overview
 
-`README.md` files are Markdown files that describe a directory.
-GitHub and Gitiles renders it when you browse the directory.
+A README is a short summary of the contents of a directory. The contents of the
+file are displayed in GitHub and Gitiles when you view the contents of the
+containing directory. README files provide critical information for people
+browsing your code, especially first-time users.
+
+This document covers how to create README files that are readable with GitHub
+and Gitiles.
+
+## Readable README files
+
+**README files must be named `README.md`.** The file name *must* end with the
+`.md` extension and is case sensitive.
 
 For example, the file /README.md is rendered when you view the contents of the
 containing directory:
@@ -23,47 +32,29 @@ index:
 
 https://gerrit.googlesource.com/gitiles/
 
-## Guidelines
+## Where to put your README
 
-**`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.
+Unlike all other Markdown files, `README.md` files should not be located inside
+your product or library's documentation directory. `README.md` files should be
+located in the top-level directory for your product or library's actual
+codebase.
 
-We recommend that top-level directories for your code have an up-to-date
+All top-level directories for a code package should 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.
+## What to put in your README
 
-### Contents
+At a minimum, your `README.md` file should contain a link to your user- and/or
+team-facing documentation.
 
-At minimum, every package-level `README.md` should include or point to the
-following information:
+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
+1.  What is in this package or library and what's it used for.
+1.  Points of contact.
+1.  Status of whether this package or 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/`.
-
-...
-```
+1.  How to use the package or library. Examples include sample code, copyable
+    `bazel run` or `bazel test` commands, etc.
+1.  Links to relevant documentation.

docguide/VERSION

@@ -1 +1 @@
-1.0
+2.0

docguide/best_practices.md

@@ -5,29 +5,28 @@
 
 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)
+1.  [Minimum Viable Documentation](#minimum-viable-documentation)
+1.  [Update Docs with Code](#update-docs-with-code)
+1.  [Delete Dead Documentation](#delete-dead-documentation)
+1.  [Prefer the Good Over the Perfect](#prefer-the-good-over-the-perfect)
+1.  [Documentation is the Story of Your Code](#documentation-is-the-story-of-your-code)
+1.  [Duplication is Evil](#duplication-is-evil)
 
-## Minimum viable documentation
+## 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.
+A small set of fresh and accurate docs is better than a large 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**.
+Write short and useful documents. Cut out everything unnecessary, including
+out-of-date, incorrect, or redundant information. Also make 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.
+See also
+[these Agile Documentation best practices](https://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm).
 
-* Identify what you really need: release docs, API docs, testing guidelines.
-* Delete cruft frequently and in small batches.
-
-## Update docs with code
+## 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
@@ -36,7 +35,7 @@ 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
+## 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
@@ -54,39 +53,37 @@ docs are in bad shape:
     recovered.
 *   Iterate.
 
-## Prefer the good over the perfect
+## Prefer the Good Over the Perfect
 
-Your documentation should be as good as possible within a reasonable time frame.
-The standards for a 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 an art. There is no perfect document, there are only proven
+methods and prudent guidelines. See [Better is better than best](./style.md).
 
-## Documentation is the story of your code
+## 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
+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
+1.  **Meaningful names**: Good naming allows the code to convey information that
+    would otherwise be relegated to comments or documentation. This includes
+    nameable entities at all levels, from local variables to classes, files, and
+    directories.
+
+2.  **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**:
+3.  **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.
+    *   **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
@@ -103,13 +100,42 @@ to detailed prose:
         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.
+        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
+4.  **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?
+
+    *   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).
+
+5.  **docs**: The contents of a good docs directory explain how to:
+
+    *   Get started using the relevant API, library, or tool.
+    *   Run its tests.
+    *   Debug its output.
+    *   Release the binary.
+
+6.  **Design docs, PRDs**: A good design doc or PRD discusses the proposed
+    implementation at length for the purpose of collecting feedback on that
+    design. However, once the code is implemented, design docs should serve as
+    archives of these decisions, not as half-correct docs (they are often
+    misused).
+
+7.  **Other external docs**: Some teams maintain documentation in other
+    locations, separate from the code, such as Google Sites, Drive, or wiki.
+    If you do maintain documentation in
+    other locations, you should clearly point to those locations from your
+    project directory (for example, by adding an obvious link to the location
+    from your project's `README.md`).
+
+## Duplication is Evil
+
+Do not write your own guide to a common Google technology or process. Link to it
+instead. If the guide doesn't exist or it's badly out of date, submit your
+updates to the appriopriate directory or create a package-level
+README.md. **Take ownership and don't be shy**: Other teams will usually welcome
+your contributions.

docguide/philosophy.md

@@ -5,33 +5,33 @@
 *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)
+\- [Laozi](https://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)
+1.  [Better is better than best](#better-is-better-than-best)
 
 ## 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, digestible content.
+*   **Scalability and interoperability** are more important than a menagerie of
+    unessential features. Scale comes from simplicity, speed, and ease.
+    Interoperability comes from unadorned, digestible content.
 
-* **Fewer distractions** make for better writing and more productive reading.
+*   **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.
+*   **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.
+*   **Markdown 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.
+*   **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
 
@@ -61,11 +61,13 @@ Contents:
   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
+## Better is better than best
 
-* **Incremental improvement is better than prolonged debate**. Patience and
-  tolerance of imperfection allow projects to evolve organically.
+*   **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.
+*   **Don't
+    [lick the cookie](https://community.redhat.com/blog/2018/09/dont-lick-the-cookie/),
+    pass the plate**. Ideas are cheap. We're drowning in potentially impactful
+    projects. Choose only those you can really handle and release those you
+    can't.

docguide/style.md

@@ -13,6 +13,8 @@ We seek to balance three goals:
 
 Contents:
 
+1.  [Minimum viable documentation](#minimum-viable-documentation)
+1.  [Better is better than best](#better-is-better-than-best)
 1.  [Capitalization](#capitalization)
 1.  [Document layout](#document-layout)
 1.  [Table of contents](#table-of-contents)
@@ -47,6 +49,43 @@ Contents:
 1.  [Tables](#tables)
 1.  [Strongly prefer Markdown to HTML](#strongly-prefer-markdown-to-html)
 
+## Minimum viable documentation
+
+A small set of fresh and accurate docs is better than a sprawling, loose
+assembly of "documentation" in various states of disrepair.
+
+The **Markdown way** 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.
+
+## Better is better than best
+
+The standards for an internal documentation review are different from the
+standards for code reviews. Reviewers should ask for improvements, but in
+general, the author should always be able to invoke the "Better/Best Rule."
+
+Fast iteration is your friend. To get long-term improvement, **authors must stay
+productive** when making short-term improvements. Set lower standards for each
+CL, so that **more such CLs** can happen.
+
+As a reviewer of a documentation CL:
+
+1.  When reasonable, LGTM immediately and trust that comments will be fixed
+    appropriately.
+2.  Prefer to suggest an alternative rather than leaving a vague comment.
+3.  For substantial changes, start your own follow-up CL instead. Especially try
+    to avoid comments of the form "You should *also*...".
+4.  On rare occasions, hold up submission if the CL actually makes the docs
+    worse. It's okay to ask the author to revert.
+
+As an author:
+
+1.  Avoid wasting cycles with trivial argument. Capitulate early and move on.
+2.  Cite the Better/Best Rule as often as needed.
+
 ## Capitalization
 
 Use the original names of products, tools and binaries, preserving the
@@ -453,7 +492,7 @@ backslash at the end of the line:
 
 <pre>
 ```shell
-$ blaze run :target -- --flag --foo=longlonglonglonglongvalue \
+$ bazel run :target -- --flag --foo=longlonglonglonglongvalue \
   --bar=anotherlonglonglonglonglonglonglonglonglonglongvalue
 ```
 </pre>