1 # Documentation Best Practices 2 3 "Say what you mean, simply and directly." - [Brian Kernighan] 4 (https://en.wikipedia.org/wiki/The_Elements_of_Programming_Style) 5 6 Contents: 7 8 1. [Minimum viable documentation](#minimum-viable-documentation) 9 1. [Update docs with code](#update-docs-with-code) 10 1. [Delete dead documentation](#delete-dead-documentation) 11 1. [Documentation is the story of your code](#documentation-is-the-story-of-your-code) 12 13 ## Minimum viable documentation 14 15 A small set of fresh and accurate docs are better than a sprawling, loose 16 assembly of "documentation" in various states of disrepair. 17 18 Write short and useful documents. Cut out everything unnecessary, while also 19 making a habit of continually massaging and improving every doc to suit your 20 changing needs. **Docs work best when they are alive but frequently trimmed, 21 like a bonsai tree**. 22 23 This guide encourages engineers to take ownership of their docs and keep 24 them up to date with the same zeal we keep our tests in good order. Strive for 25 this. 26 27 * Identify what you really need: release docs, API docs, testing guidelines. 28 * Delete cruft frequently and in small batches. 29 30 ## Update docs with code 31 32 **Change your documentation in the same CL as the code change**. This keeps your 33 docs fresh, and is also a good place to explain to your reviewer what you're 34 doing. 35 36 A good reviewer can at least insist that docstrings, header files, README.md 37 files, and any other docs get updated alongside the CL. 38 39 ## Delete dead documentation 40 41 Dead docs are bad. They misinform, they slow down, they incite despair in 42 engineers and laziness in team leads. They set a precedent for leaving behind 43 messes in a code base. If your home is clean, most guests will be clean without 44 being asked. 45 46 Just like any big cleaning project, **it's easy to be overwhelmed**. If your 47 docs are in bad shape: 48 49 * Take it slow, doc health is a gradual accumulation. 50 * First delete what you're certain is wrong, ignore what's unclear. 51 * Get your whole team involved. Devote time to quickly scan every doc and make 52 a simple decision: Keep or delete? 53 * Default to delete or leave behind if migrating. Stragglers can always be 54 recovered. 55 * Iterate. 56 57 ## Prefer the good over the perfect 58 59 Your documentation should be as good as possible within a reasonable time frame. 60 The standards for an documentation review are different from the 61 standards for code reviews. Reviewers can and should ask for improvements, but 62 in general, the author should always be able to invoke the "Good Over Perfect 63 Rule". It's preferable to allow authors to quickly submit changes that improve 64 the document, instead of forcing rounds of review until it's "perfect". Docs are 65 never perfect, and tend to gradually improve as the team learns what they really 66 need to write down. 67 68 ## Documentation is the story of your code 69 70 Writing excellent code doesn't end when your code compiles or even if your 71 test coverage reaches 100%. It's easy to write something a computer understands, 72 it's much harder to write something both a human and a computer understand. Your 73 mission as a Code Health-conscious engineer is to **write for humans first, 74 computers second.** Documentation is an important part of this skill. 75 76 There's a spectrum of engineering documentation that ranges from terse comments 77 to detailed prose: 78 79 1. **Inline comments**: The primary purpose of inline comments is to provide 80 information that the code itself cannot contain, such as why the code is 81 there. 82 83 2. **Method and class comments**: 84 85 * **Method API documentation**: The header / Javadoc / docstring 86 comments that say what methods do and how to use them. This 87 documentation is **the contract of how your code must behave**. The 88 intended audience is future programmers who will use and modify your 89 code. 90 91 It is often reasonable to say that any behavior documented here should 92 have a test verifying it. This documentation details what arguments the 93 method takes, what it returns, any "gotchas" or restrictions, and what 94 exceptions it can throw or errors it can return. It does not usually 95 explain why code behaves a particular way unless that's relevant to a 96 developer's understanding of how to use the method. "Why" explanations 97 are for inline comments. Think in practical terms when writing method 98 documentation: "This is a hammer. You use it to pound nails." 99 100 * **Class / Module API documentation**: The header / Javadoc / docstring 101 comments for a class or a whole file. This documentation gives a brief 102 overview of what the class / file does and often gives a few short 103 examples of how you might use the class / file. 104 105 Examples are particularly relevant when there's several distinct ways to 106 use the class (some advanced, some simple). Always list the simplest 107 use case first. 108 109 3. **README.md**: A good README.md orients the new user to the directory and 110 points to more detailed explanation and user guides: 111 * What is this directory intended to hold? 112 * Which files should the developer look at first? Are some files an API? 113 * Who maintains this directory and where I can learn more? 114 115 See the [README.md guidelines](READMEs.md). 116
