From dc0c0923f14b65712d4e8603cbab66d1626cfaff Mon Sep 17 00:00:00 2001 From: Mike Frysinger Date: Mon, 8 Jul 2024 12:13:08 -0400 Subject: [PATCH] docguide: pull in updates from internal docs --- docguide/READMEs.md | 75 +++++++++++------------- docguide/VERSION | 2 +- docguide/best_practices.md | 116 +++++++++++++++++++++++-------------- docguide/philosophy.md | 42 +++++++------- docguide/style.md | 41 ++++++++++++- 5 files changed, 167 insertions(+), 109 deletions(-) diff --git a/docguide/READMEs.md b/docguide/READMEs.md index 5854af2..a024961 100644 --- a/docguide/READMEs.md +++ b/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 +## What to put in your README -Use `README.md`. +At a minimum, your `README.md` file should contain a link to your user- and/or +team-facing documentation. -Files named `README` are not displayed in the directory view in Gitiles. +Every package-level `README.md` should include or point to the following +information: -### 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 +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. diff --git a/docguide/VERSION b/docguide/VERSION index d3827e7..cd5ac03 100644 --- a/docguide/VERSION +++ b/docguide/VERSION @@ -1 +1 @@ -1.0 +2.0 diff --git a/docguide/best_practices.md b/docguide/best_practices.md index 22e5827..d20f317 100644 --- a/docguide/best_practices.md +++ b/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. diff --git a/docguide/philosophy.md b/docguide/philosophy.md index 5b3813a..690c3e4 100644 --- a/docguide/philosophy.md +++ b/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. diff --git a/docguide/style.md b/docguide/style.md index 917aff6..dc7e928 100644 --- a/docguide/style.md +++ b/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: 
 ```shell
-$ blaze run :target -- --flag --foo=longlonglonglonglongvalue \
+$ bazel run :target -- --flag --foo=longlonglonglonglongvalue \
   --bar=anotherlonglonglonglonglonglonglonglonglonglongvalue
 ```