OLD | NEW |
1 # Documentation Best Practices | 1 # Documentation Best Practices |
2 | 2 |
3 "Say what you mean, simply and directly." - [Brian Kernighan] | 3 "Say what you mean, simply and directly." - [Brian Kernighan] |
4 (http://en.wikipedia.org/wiki/The_Elements_of_Programming_Style) | 4 (http://en.wikipedia.org/wiki/The_Elements_of_Programming_Style) |
5 | 5 |
6 [TOC] | 6 [TOC] |
7 | 7 |
8 ## Minimum viable documentation | 8 ## Minimum viable documentation |
9 | 9 |
10 A small set of fresh and accurate docs is better than a large | 10 A small set of fresh and accurate docs is better than a large |
(...skipping 79 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
90 points to more detailed explanation and user guides: | 90 points to more detailed explanation and user guides: |
91 * What is this directory intended to hold? | 91 * What is this directory intended to hold? |
92 * Which files should the developer look at first? Are some files an API? | 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? | 93 * Who maintains this directory and where I can learn more? |
94 | 94 |
95 4. **Design docs, PRDs**: A good design doc or PRD discusses the proposed | 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 | 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 | 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 | 98 archives of these decisions, not as half-correct docs (they are often |
99 misused). See | 99 misused). See |
100 [Implementation state](#implementation_state_determines_document_location) | 100 [Implementation state](#Implementation-state-determines-document-repository) |
101 below. | 101 below. |
102 | 102 |
103 ## Implementation state determines document repository | 103 ## Implementation state determines document repository |
104 | 104 |
105 **If the doc is about implemented code, put it in README.md**. If it's | 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, | 106 pre-implementation discussion, including Design docs, PRDs, and presentations, |
107 keep it in shared Drive folders. | 107 keep it in shared Drive folders. |
108 | 108 |
109 ## Duplication is evil | 109 ## Duplication is evil |
110 | 110 |
111 Do not write your own guide to a common technology or process. Link to it | 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 | 112 instead. If the guide doesn't exist or it's badly out of date, submit your |
113 updates to the appropriate docs/ directory or create a package-level | 113 updates to the appropriate docs/ directory or create a package-level |
114 README.md. **Take ownership and don't be shy**: Other teams will usually welcome | 114 README.md. **Take ownership and don't be shy**: Other teams will usually welcome |
115 your contributions. | 115 your contributions. |
OLD | NEW |