search

StyleGuides / WritingStyleGuide

The official Red Hat guide to writing clear, concise, and consistent technical documentation.
Creative Commons Attribution Share Alike 4.0 International
72 stars 20 forks source link

Review sections on capitalisation #415

Open daobrien opened 2 years ago

daobrien commented 2 years ago

We should review our guidance to take into account the following from the Corporate guide:

capitalization

If it's not the official name of a Red Hat offering (with a SKU) or department, don't capitalize it (even if it seems important). Capitalize job titles. Example: "Bob Smith, Group Manager, Acme Widgets" or "Acme Widgets Group Manager Bob Smith." Do not capitalize job personas. See also department names, commands, personas. Do not capitalize domain names, even when they begin a sentence (but try to avoid starting a sentence with a domain name). Example: "redhat.com is awesome." When writing a domain name that does not belong to Red Hat, adhere to that entity's capitalization. If you can't determine how they capitalize it, default to Red Hat's style. Keep in mind that screen readers may have trouble speaking domain names with more than 1 word. Use good judgment in deciding how to write multiword domain names; if needed for clarity, use CamelCase. See also URLs.

department names

The preferred word is "team," regardless of size or function. Do not use "business unit" in external-facing documents. Use "organization" to distinguish a department from its subteams or otherwise call attention to its large, multiteam nature: "The OpenShift Engineering team is part of the Red Hat Engineering organization." When displayed as a title or caption, capitalize all words including team or organization: "Red Hat Finance Team," "Red Hat IT Organization" When using in context or in a sentence, don't capitalize words like team or organization: "As a member of the Red Hat Finance team...," "...with our Global Workplace Solutions team."

commands (Needs a new title) (This is quite different from CMOS and the examples in this section in the Corp guide really need updating.)

Many proper nouns and other words, especially commands and names of open source projects, begin with a lowercase letter. How should those words be treated when they begin a sentence? AP Style guidance:

For words like iPad or iPod, AP Style recommends that they be styled with an uppercase letter when beginning a sentence. So "IPads are selling poorly in Q4" or "IPods are no longer the best-selling holiday item now that people listen to music on their phones." AP Style has no guidance for command names. However, Linux makes distinctions based on capitalization that would make a capitalized command incorrect. For example, with "ls" and "Ls"—a user reading a document, blog post, or other material where the command name has been capitalized may have reason to expect they could use Ls but that will be met with an error.

daobrien commented 1 year ago

We probably need to decide how much of this we want to integrate into the RH Guide. The "department names" section, in particular, might not need inclusion.