github.com/ddev/ddev@v1.23.2-0.20240519125000-d824ffe36ff3/docs/content/developers/writing-style-guide.md (about) 1 --- 2 search: 3 boost: .5 4 --- 5 # Writing Style Guide 6 7 This page formalizes the writing conventions we aspire to use in the documentation. 8 It’s a living statement of intent and a reference for all contributors. 9 10 ## Voice and Tone 11 12 In the spirit of the [Code of Conduct](../users/code-of-conduct.md), we want to be clear and encouraging for everyone that bothers to read DDEV’s documentation, rewarding the time and attention they choose to give to it. 13 14 ### Beginner-Friendly, Expert-Compatible 15 16 Write so a DDEV beginner can follow your guidance and a DDEV veteran could use the same content as a reference. 17 18 <!-- textlint-disable --> 19 20 | Write This 👍 | Not This ❌ 21 | -- | -- 22 | You can run `ddev restart` to apply changes you’ve made to your global `~/.ddev/global_config.yaml` or per-project `.ddev/config.yaml`. | Just `ddev restart` to apply YAML config changes. 23 24 <!-- textlint-enable --> 25 26 ### Be Efficient and Direct 27 28 Brevity makes for good documentation! 29 30 Few read the docs from start to finish like a book, and explanation can be a barrier to learning. Get to the point, avoiding parentheticals and mid-sentence notes that interrupt the main flow. 31 32 Omit extraneous explanation or decorative language that doesn’t help the reader. Instructions don’t need to include “please”. Provide some context for anchor links without overloading them to hinder flow. 33 34 | Write This 👍 | Not This ❌ 35 | -- | -- 36 | Run `ddev start` and launch the site in a browser. | Please run `ddev start`, then launch the site in a browser. 37 | Learn more on the [Extending](../users/extend/customization-extendibility.md) page. | (You can also learn more about this and related topics in [Providing Custom Environment Variables to a Container](../users/extend/customization-extendibility.md).) 38 39 ### Avoid “Just” and “Easy” 40 41 <!-- textlint-disable --> 42 43 Try not to use language that [may talk down to the reader](https://justsimply.dev/). You may intend for “it’s easy” to be reassuring, but it’s a subjective judgment that can convince someone struggling that they’re doing it wrong. Things could instead be “straightforward” if they’re without nuance, “simple” if they don’t involve complex actions or concepts, or “quick” if they involve one or two steps that’d be fast even on someone’s worst day with the slowest-imaginable machine. 44 45 Similarly, “just do X” suggests that “X” should be easy or obvious. Most of the time “just” can be omitted and everyone wins. 46 47 <!-- textlint-enable --> 48 49 If you’d like to reassure the reader something is easy, illustrate it with a demonstration and let them draw their own conclusion! 50 51 <!-- textlint-disable --> 52 53 | Write This 👍 | Not This ❌ 54 | -- | -- 55 | Change your project’s PHP version by either editing `.ddev/config.yaml` to set `php_version: "8.2"`, or by running `ddev config --php-version=8.2`, followed by running `ddev restart`. | It’s easy to change your project’s PHP version! Just edit your project’s `.ddev/config.yaml` to set `php_version: "8.2"`, or run `ddev config --php-version=8.2`, followed by running `ddev restart`. 56 57 <!-- textlint-enable --> 58 59 ## Writing Style 60 61 DDEV’s documentation should be consistent throughout, which benefits both the reader taking in information and the contributor looking for examples to follow. 62 63 !!!tip "Read It Aloud" 64 If you get tripped up speaking your words out loud, someone else will get tripped up reading them, too. 65 66 ### Use Correct Capitalization and Punctuation 67 68 Write with appropriate grammar and style for U.S. English, including capitalization and punctuation. Variations in spelling and writing style make the documentation harder to read, and we want to be respectful of the reader’s time and attention. 69 70 <!-- textlint-disable --> 71 72 | Write This 👍 | Not This ❌ 73 | -- | -- 74 | Let’s not capitalize random words for emphasis. | Let’s not Capitalize random Words for emphasis. 75 | That organization uses a lovely American color. | That organisation uses a lovely American colour. 76 | We can use “curly quotes” now that we’re post-typewriter. | We can use "curly quotes" now that we're post-typewriter. 77 78 <!-- textlint-enable --> 79 80 ### “Run” Commands 81 82 We “run” commands. We don’t “do” them, and the command itself is not a verb. Whenever possible, reinforce that a given thing in backticks is intended as a console command by using the word “run” before it. 83 84 <!-- textlint-disable --> 85 86 | Write This 👍 | Not This ❌ 87 | -- | -- 88 | Run `ddev config` to set up your project. | Do `ddev config` to set up your project.<br>You can `ddev config` to set up your project. 89 | If you get stuck, run `ddev restart`. | If you get stuck, just `ddev restart`. 90 91 <!-- textlint-enable --> 92 93 ### Use Active Third Person 94 95 Avoid impersonal language featuring unknown individuals or shadowy organizations. 96 “It is recommended,” for example, could be a warmer “we recommend” or “Laravel users recommend”. 97 98 Write on behalf of the community and not yourself—use “we” and not “I”. 99 100 <!-- textlint-disable --> 101 102 | Write This 👍 | Not This ❌ 103 | -- | -- 104 | We recommend Colima for the best performance. | It is recommended for performance that you use Colima. 105 | Some prefer Redis for runtime caches. | I like using Redis for runtime caches. 106 107 <!-- textlint-enable --> 108 109 ### Write Once and Link 110 111 Try to keep from repeating yourself in the documentation. Instead, write carefully and link to that well-crafted specimen, whether it’s across the page or off to another section. This has two benefits: 112 113 1. Easier maintenance with less chance of redundant information becoming stale. 114 2. Subtle reinforcement of documentation structure that helps the reader learn where to find answers, rather than answering the same thing in different places. 115 116 ### Mind Your Context 117 118 It’s easy to get lost in documentation; don’t assume the reader is always following your words. Take care to bring the reader with you, especially if there are steps that involve different applications or distinct areas of concern. 119 120 <!-- textlint-disable --> 121 122 | Write This 👍 | Not This ❌ 123 | -- | -- 124 | 1. In Docker Desktop, go to *Resources* → *Advanced* and set “Memory” to 6GB.<br>2. From your terminal, run `ddev restart`.<br>3. In your text editor, open `.ddev/config.yaml` and set `php_version: "8.1"`. | 1. Go to *Resources* → *Advanced* and set “Memory” to 6GB.<br>2. Run `ddev restart`.<br>3. Set `php_version: "8.1"`. 125 | Once you’ve [installed a Docker provider](../users/install/docker-installation.md), you’re ready to install DDEV! | Docker or an alternative is required before anything will work with DDEV. This is pretty easy on most environments; see the [Docker Installation](../users/install/docker-installation.md) page to help sort out the details. 126 127 <!-- textlint-enable --> 128 129 ### Avoid Starting with Asides 130 131 The beginning of a page or section should introduce what the rest of the content is about. Try to avoid starting with asides or reminders that get in the way of this initial statement of purpose. 132 133 Never tell the reader to “remember” something they may not have been introduced to yet. 134 135 ### Use Tips 136 137 Avoid using “Note:” to signal an aside. Most sentences work fine without it, and for discreet notes we have `!!!note`, `!!!tip`, and `!!!warning` conventions. 138 139 Use one of these callouts for text that can stand on its own and be skipped, or for an urgent message that needs greater visual emphasis. 140 141 Summarize the callout’s contents with a succinct heading whenever you can, so anyone skimming can know whether to read the callout’s supporting text. 142 143 ``` 144 !!!note "This is a note." 145 Use it for extraneous asides. 146 147 !!!tip "This is a tip." 148 Use it for helpful asides. 149 150 !!!warning "This is a warning." 151 Use it for asides that should have urgent emphasis. 152 153 !!!note 154 This is a note without a heading, which should only be used with the author isn’t clever enough to come up with a succinct one. (The “Note” is added automatically.) 155 ``` 156 157 !!!note "This is a note." 158 Use it for extraneous asides. 159 160 !!!tip "This is a tip." 161 Use it for helpful asides. 162 163 !!!warning "This is a warning." 164 Use it for asides that should have urgent emphasis. 165 166 !!!note 167 This is a note without a heading, which should only be used with the author isn’t clever enough to come up with a succinct one. (The “Note” is automatically added.) 168 169 **Note:** we want to avoid callouts like this sentence, that should either be tips or flow naturally with their surrounding text. If any documentation *shouldn’t* be noted by the reader, get rid of it. 170 171 ### Use Correct Proper Nouns 172 173 #### DDEV != `ddev` 174 175 DDEV is a product and `ddev` is a binary or console command. DDEV should always be uppercase, and `ddev` should always be in backticks. DDEV-Local and DDEV-Live are former product incarnations that shouldn’t be found in modern documentation. 176 177 <!-- textlint-disable --> 178 179 | Write This 👍 | Not This ❌ 180 | -- | -- 181 | DDEV is wonderful! | Ddev is wonderful!<br>ddev is wonderful!<br>DDEV-Local is wonderful! 182 | Run `ddev`. | Run ddev.<br>Run DDEV. 183 184 <!-- textlint-enable --> 185 186 #### Products, Organizations, and Protocols 187 188 When in doubt, honor whatever name a product or organization uses in its official materials. 189 Use backticks to differentiate between a product and command, like DDEV vs. `ddev`. 190 191 <!-- textlint-disable --> 192 193 | Write This 👍 | Not This ❌ 194 | -- | -- 195 | AMD64, ARM64, and Apple Silicon | amd64, arm64, M1 Macs 196 | Apache | apache 197 | Bash or `bash` | bash 198 | Blackfire | blackfire, Blackfire.io 199 | Chocolatey | chocolatey 200 | Colima or `colima` | colima 201 | Composer or `composer` | composer 202 | Docker or `docker` | docker 203 | Drush or `drush` | drush 204 | Git | git 205 | Git Bash | git bash 206 | GitHub or `github` | Github 207 | Gitpod or `gitpod` | Gitpod.io, GitPod 208 | GoLand | Goland 209 | Google | google 210 | Homebrew | homebrew 211 | HTTP, HTTPS, SSH, `http`, `https`, `ssh` | http, https, ssh 212 | IPv4, IPv6 | IPV4, IPV6, ipv4, ipv6 213 | Linux | linux 214 | nginx or `nginx` | Nginx, NGINX 215 | Node.js or `node` | Node, node 216 | NFS | nfs 217 | Pantheon | pantheon, Pantheon.io 218 | PHP or `php` | php 219 | PhpStorm | PHPStorm, PHPstorm, Phpstorm 220 | PHPUnit or `phpunit` | phpunit, PHPunit 221 | PostgreSQL | Postgres 222 | Terminus | terminus 223 | Windows | windows 224 | Xdebug | XDebug, xDebug 225 226 <!-- textlint-enable --> 227 228 ### Quote Copied Text 229 230 If you’re quoting a human being or a message lifted verbatim from some other source (outside a fenced code block), make sure it ends up in a `<blockquote>` element: 231 232 ``` 233 > Error: your quote style should not always be in a fenced block. 234 ``` 235 236 > Error: your quote style should not always be in a fenced block. 237 238 ### Other Recommendations 239 240 One-off tips that don’t fit nicely into any of the sections above: 241 242 <!-- textlint-disable --> 243 244 - Pluralize “CMS” as “CMSes”, not “CMSs”. 245 - Use all-caps references for file *types* like JSON, YAML and CSS. 246 - Wrap file *extensions* in backticks like `.json`, `.yaml`, and `.css`. 247 - Wrap references to files, directories, images and commands in backticks. 248 - Use Title Case for headings wherever it makes sense. 249 - Link to related services and topics where convenient—usually first use on a given page. 250 - Use `<kbd>` elements for representing literal keystrokes. 251 - Use sequential numbers for numbered lists in the source Markdown, regardless of how they’re eventually rendered. 252 - Try to maintain parallel format for list items. 253 254 | Write This 👍 | Not This ❌ 255 | -- | -- 256 | web server | webserver 257 | add-on | addon 258 | JSON, YAML, CSS | json, Yaml, css 259 | `.json`, `.yaml`, `.css`, `~/.ddev` | .json, .yaml, .css, ~/.ddev 260 | <kbd>CTRL</kbd> + <kbd>C</kbd> | control-c, control + c, ctrl+c 261 | *Menu Item* → *Another Menu Item* → *Setting* | Menu Item>Another Menu Item>Setting<br>Menu Item -> Another Menu Item -> Setting 262 | several CMSes | several CMSs, several CMS’s 263 | How to Reticulate Splines | How to reticulate splines 264 | 1. Run `command`.<br>2. Edit file.<br>3. Restart computer. | 1. `command`<br>2. Edit file.<br>3. Additionally, restart your computer. 265 266 <!-- textlint-enable -->