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 -->