Writing Style Guide¶

This page formalizes the writing conventions we aspire to use in the documentation.
It’s a living statement of intent and a reference for all contributors.

Voice and Tone¶

In the spirit of the Code of Conduct, 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.

Beginner-Friendly, Expert-Compatible¶

Write so a DDEV beginner can follow your guidance and a DDEV veteran could use the same content as a reference.

Be Efficient and Direct¶

Brevity makes for good documentation!

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.

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.

Avoid “Just” and “Easy”¶

Try not to use language that may talk down to the reader. 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.

Similarly, “just do X” suggests that “X” should be easy or obvious. Most of the time “just” can be omitted and everyone wins.

If you’d like to reassure the reader something is easy, illustrate it with a demonstration and let them draw their own conclusion!

Writing Style¶

DDEV’s documentation should be consistent throughout, which benefits both the reader taking in information and the contributor looking for examples to follow.

Use Correct Capitalization and Punctuation¶

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.

“Run” Commands¶

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.

Use Active Third Person¶

Avoid impersonal language featuring unknown individuals or shadowy organizations.
“It is recommended,” for example, could be a warmer “we recommend” or “Laravel users recommend”.

Write on behalf of the community and not yourself—use “we” and not “I”.

Write Once and Link¶

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:

1. Easier maintenance with less chance of redundant information becoming stale.
2. Subtle reinforcement of documentation structure that helps the reader learn where to find answers, rather than answering the same thing in different places.

Mind Your Context¶

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.

Avoid Starting with Asides¶

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.

Never tell the reader to “remember” something they may not have been introduced to yet.

Use Tips¶

Avoid using “Note:” to signal an aside. Most sentences work fine without it, and for discreet notes we have !!!note, !!!tip, and !!!warning conventions.

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.

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.

!!!note "This is a note."
    Use it for extraneous asides.

!!!tip "This is a tip."
    Use it for helpful asides.

!!!warning "This is a warning."
    Use it for asides that should have urgent emphasis.

!!!note
    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.)

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.

Use Correct Proper Nouns¶

DDEV != ddev¶

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.

Products, Organizations, and Protocols¶

When in doubt, honor whatever name a product or organization uses in its official materials.
Use backticks to differentiate between a product and command, like DDEV vs. ddev.

Quote Copied Text¶

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:

> Error: your quote style should not always be in a fenced block.

Error: your quote style should not always be in a fenced block.

Other Recommendations¶

One-off tips that don’t fit nicely into any of the sections above:

• Pluralize “CMS” as “CMSes”, not “CMSs”.
• Use all-caps references for file types like JSON, YAML and CSS.
• Wrap file extensions in backticks like .json, .yaml, and .css.
• Wrap references to files, directories, images and commands in backticks.
• Use Title Case for headings wherever it makes sense.
• Link to related services and topics where convenient—usually first use on a given page.
• Use <kbd> elements for representing literal keystrokes.
• Use sequential numbers for numbered lists in the source Markdown, regardless of how they’re eventually rendered.
• Try to maintain parallel format for list items.