docs/documentation_best_practices.md

   1 # Documentation Best Practices
   2
   3 "Say what you mean, simply and directly." - [Brian Kernighan]
   4 (http://en.wikipedia.org/wiki/The_Elements_of_Programming_Style)
   5
   6 [TOC]
   7
   8 ## Minimum viable documentation
   9
  10 A small set of fresh and accurate docs is better than a large
  11 assembly of "documentation" in various states of disrepair.
  12
  13 Write short and useful documents. Cut out everything unnecessary, while also
  14 making a habit of continually massaging and improving every doc to suit your
  15 changing needs. **Docs work best when they are alive but frequently trimmed,
  16 like a bonsai tree**.
  17
  18 ## Update docs with code
  19
  20 **Change your documentation in the same CL as the code change**. This keeps your
  21 docs fresh, and is also a good place to explain to your reviewer what you're
  22 doing.
  23
  24 ## Delete dead documentation
  25
  26 Dead docs are bad. They misinform, they slow down, they incite despair in
  27 new community members and laziness in existing ones. They set a precedent
  28 for leaving behind messes in a code base. If your home is clean, most
  29 guests will be clean without being asked.
  30
  31 Just like any big cleaning project, **it's easy to be overwhelmed**. If your
  32 docs are in bad shape:
  33
  34 *   Take it slow, doc health is a gradual accumulation.
  35 *   First delete what you're certain is wrong, ignore what's unclear.
  36 *   Get the whole community involved. Devote time to quickly scan every doc and
  37     make a simple decision: Keep or delete?
  38 *   Default to delete or leave behind if migrating. Stragglers can always be
  39     recovered.
  40 *   Iterate.
  41
  42 ## Prefer the good over the perfect
  43
  44 Documentation is an art. There is no perfect document, there are only proven
  45 methods and prudent guidelines. See
  46 go/g3doc-style#good.
  47
  48 ## Documentation is the story of your code
  49
  50 Writing excellent code doesn't end when your code compiles or even if your
  51 test coverage reaches 100%. It's easy to write something a computer understands,
  52 it's much harder to write something both a human and a computer understand. Your
  53 mission as a Code Health-conscious engineer is to **write for humans first,
  54 computers second.** Documentation is an important part of this skill.
  55
  56 There's a spectrum of engineering documentation that ranges from terse comments
  57 to detailed prose:
  58
  59 1.  **Inline comments**: The primary purpose of inline comments is to provide
  60     information that the code itself cannot contain, such as why the code is
  61     there.
  62
  63 2.  **Method and class comments**:
  64
  65     *   **Method API documentation**: The header / Javadoc / docstring
  66         comments that say what methods do and how to use them. This
  67         documentation is **the contract of how your code must behave**. The
  68         intended audience is future programmers who will use and modify your
  69         code.
  70
  71         It is often reasonable to say that any behavior documented here should
  72         have a test verifying it. This documentation details what arguments the
  73         method takes, what it returns, any "gotchas" or restrictions, and what
  74         exceptions it can throw or errors it can return. It does not usually
  75         explain why code behaves a particular way unless that's relevant to a
  76         developer's understanding of how to use the method. "Why" explanations
  77         are for inline comments. Think in practical terms when writing method
  78         documentation: "This is a hammer. You use it to pound nails."
  79
  80     *   **Class / Module API documentation**: The header / Javadoc / docstring
  81         comments for a class or a whole file. This documentation gives a brief
  82         overview of what the class / file does and often gives a few short
  83         examples of how you might use the class / file.
  84
  85         Examples are particularly relevant when there's several distinct ways to
  86         use the class (some advanced, some simple). Always list the simplest
  87         use case first.
  88
  89 3.  **README.md**: A good README.md orients the new user to the directory and
  90     points to more detailed explanation and user guides:
  91     * What is this directory intended to hold?
  92     * Which files should the developer look at first? Are some files an API?
  93     * Who maintains this directory and where I can learn more?
  94
  95 4.  **Design docs, PRDs**: A good design doc or PRD discusses the proposed
  96     implementation at length for the purpose of collecting feeback on that
  97     design. However, once the code is implemented, design docs should serve as
  98     archives of these decisions, not as half-correct docs (they are often
  99     misused). See
 100     [Implementation state](#implementation_state_determines_document_location)
 101     below.
 102
 103 ## Implementation state determines document repository
 104
 105 **If the doc is about implemented code, put it in README.md**. If it's
 106 pre-implementation discussion, including Design docs, PRDs, and presentations,
 107 keep it in shared Drive folders.
 108
 109 ## Duplication is evil
 110
 111 Do not write your own guide to a common technology or process. Link to it
 112 instead. If the guide doesn't exist or it's badly out of date, submit your
 113 updates to the appriopriate docs/ directory or create a package-level
 114 README.md. **Take ownership and don't be shy**: Other teams will usually welcome
 115 your contributions.