| 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 |
|---|
Chromium Code Reviews
Issue 2695963002:
Update web-platform-tests docs (Closed)
