Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Formatting and proper noun tune-up #4200

Merged
merged 109 commits into from Oct 5, 2022

Conversation

mattstein
Copy link
Sponsor Collaborator

@mattstein mattstein commented Sep 9, 2022

This PR is for tracking some of the initial cleanup work involved on #4188.

  • Replace instances of “DDEV-Local”, “DDEV-Live”, and improperly-lowercased “ddev” with “DDEV”
  • Wrap legitimate instances of “ddev”—used for references to the command or binary file—in backticks
  • Consistently use smart punctuation / curly quotes
  • Replace instances of “docker” with “Docker”
  • Make sure the words AMD64, Apache, ARM64, Bash, Blackfire, Chocolatey, Colima, Composer, Drush, Git, Git Bash, GitHub, Gitpod, GoLand, Google, Homebrew, HTTP, HTTPS, IPv4, IPv6, Linux, NFS, nginx, Node.js, Pantheon, PHP, PhpStorm, PHPUnit, PostgreSQL, SSH, Terminus, Windows, and Xdebug are all properly capitalized
  • Make sure “web server” always appears as two words in common usage (not “webserver”)
  • Make sure CMS plural is “CMSes”, not “CMSs”
  • Limit use of the phrases like “of course” and “it’s easy”
  • Replace unexpected first-person “I” with “we”
  • Use all-caps references for file extensions like JSON, YAML, CSS, etc.
  • Generally reduce use of parentheses and asides to improve flow and readability
  • Wrap references to files, directories, images and commands in backticks
  • Link to related services and topics where convenient—usually first use on a given page
  • Use Title Case for headings wherever it makes sense
  • Introduce <kbd> elements for representing literal keystrokes
  • Activate speaker for warmth when possible (“we recommend” instead of “it is recommended”)
  • Avoid telling someone to “remember” information that hasn’t yet been introduced
  • Improve consistency of !!!note, !!!tip and !!!warning callouts for asides, as opposed to Note: prefixes and other variations
  • Consistently represent click paths with italics and arrows (General SettingsExperimental FeaturesEnable Nurb Splooping)

Edits are tediously separated and described in smallish commits.

Replace “DDEV-Local” + “DDEV-Live”, and lowercase “ddev” when it’s related to the product and not the command or binary. Curly quotes for possessive form, backticks for binary or command references.
@mattstein mattstein changed the title Standardize usage of “DDEV” and other proper nouns Formatting and proper noun tune-up Sep 9, 2022
@github-actions
Copy link

github-actions bot commented Sep 9, 2022

Proper nouns, heading style, abolition of “just”, smart quotes, links, and edits for brevity and clarity.
Smart quotes, backticks, heading and list formatting, edits for brevity and clarity.
Backticks, smart quotes, list formatting, capitalization, minor edits for clarity.
Took a wild stab at editing for clarity.
Plus some bonus spaces around arrows (`→`) because I had to.
Smart quotes, list+heading formatting, backticks, “I” → “we”, misc. capitalization, various edits for brevity and clarity.
Title casing, smart quotes, minor edits for brevity and clarity, active speaker, more consistent use of `!!!tip` and `!!!warning` instead of callouts.
DDEV already clear from context, and `&` shortens navigation + page title for better readability.
@mattstein
Copy link
Sponsor Collaborator Author

Worked through docs/content/developers/, and confused about the single Markdown linting error I can’t get rid of:

docs/content/developers/release-management.md:82:68 MD051/link-fragments Link fragments should be valid [Context: "upstream instructions"]
make: *** [markdownlint] Error 1

The heading changed so it was correct to call it out at first. But it should be right now and it behaves fine in my browser. Just rambling to myself and will come back to it later.

mattstein and others added 5 commits October 4, 2022 11:04
Co-authored-by: Randy Fay <randy@randyfay.com>
Co-authored-by: Randy Fay <randy@randyfay.com>
Co-authored-by: Matt Stein <m@ttste.in>
Attempted to preserve `exec-host` example in some form, and move (rather than delete) Drupal 8 Composer install step.
@mattstein
Copy link
Sponsor Collaborator Author

Not sure how I managed to break the Buildkit tests @rfay, but otherwise ready to roll!

  • Merged or resolved all suggestions. (Some minor edits, and a comment for any non-merged suggestion!)
  • Restored headings for all tabular content, which also meant on the Shell Completion & Autocomplete page which didn’t have them to start with.
  • Merged upstream changes, which was straightforward and not scary.
  • Made sure spellcheck is okay with “Symfony” and “xz’d”—also removed my curly-apostrophe variants which apparently aren’t needed after all. 🤷‍♂️

@rfay
Copy link
Member

rfay commented Oct 4, 2022

Restarted, but TestComposerVersion may in fact be broken, we'll see what happens.

@rfay
Copy link
Member

rfay commented Oct 4, 2022

Looks like it's all going to pass, let me know when it's ready to pull!

@mattstein mattstein requested a review from rfay October 5, 2022 16:59
@mattstein
Copy link
Sponsor Collaborator Author

mattstein commented Oct 5, 2022

Tests finally finished, resubmitted for review! (Ready to pull.)

@rfay rfay changed the title Formatting and proper noun tune-up [docs] Formatting and proper noun tune-up Oct 5, 2022
Copy link
Member

@rfay rfay left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yay, thanks!

@rfay rfay merged commit a94f9d7 into ddev:master Oct 5, 2022
@mattstein mattstein deleted the docs/consistency-improvement branch October 5, 2022 18:13
@mattstein mattstein mentioned this pull request Dec 8, 2022
1 task
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants