tiennm99/styleguide
1
0 Fork 0
mirror of https://github.com/tiennm99/styleguide.git synced 2026-10-12 18:16:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

docguide: pull in updates from internal docs

Browse Source
This commit is contained in:
Mike Frysinger committed 2024-07-08 15:16:10 -04:00
1 parent 36c0e3a531
commit dc0c0923f1
5 files changed
+167 -109
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docguide/READMEs.md
+33 -42
View File
@@ -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.
docguide/VERSION
+1 -1
View File
@@ -1 +1 @@
1.0
2.0
docguide/best_practices.md
+71 -45
View File
@@ -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
+22 -20
View File
@@ -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
+40 -1
View File
@@ -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>