Word Usage Guide

Google's developer documentation style guide includes a Word List page that specifies how certain words and phrases ought to be used and styled in documentation. However, it is not all-encompassing and there are a number of words and phrases that appear frequently in Chainguard's documentation that aren't specified in the style guide.

Our goal in maintaining this guide is to help us achieve a consistent tone and voice across all of Chainguard's content.

Terms List

Any terms or phrases should be styled as they appear in this list. For example, the "c" in "Cosign" is capitalized; this means it should always be capitalized when referring to the container signing tool. Conversely, the "apk" entry specifies that it should never be capitalized; this includes at the beginning of a sentence or in a step title.

• apk - never capitalized
• apko - never capitalized
• Chainguard
• Chainguard Containers - The product is no longer called "Chainguard Images." When speaking about images generally, prioritize calling them "container images," but just "images" is fine "container images" gets too awkward or repetitve.
• Cosign
• cyberattack - not "cyber attack"
• distribution - as in "Linux distribution." distro is also acceptable
• Fulcio
• Gb - gigabit
• GB - gigabyte
  • include a space between the number and the unit, meaning "10 MB" instead of "10MB"
• GitHub
• Linux
• melange - never capitalized
• multi-stage - not "multistage"
• open source - noun
• open-source - adjective
  • include a hyphen (as in "open-source") when used as an adjective
• README - not "Readme"
• Rekor
• SBOM
• SBOMs - plural. When writing out the full phrase as a plural, use "Software Bills of Materials"
• Sigstore
• single sign-on - note the lower-case usage, per the Google style guide
• Wolfi

Other general rules of thumb

In addition to the specific terms listed in the previous section, here are some general guidelines to keep in mind as you produce content at Chainguard.

• Default to US English spellings
• If you plan to use an acronym throughout a tutorial, its first appearance should be within a pair of parentheses after the longer, fully written-out phrase, as in "You can download the image's software bill of materials (SBOM)...."
• When discussing a third-party product or software, defer to the styling employed by the project's website or documentation. For example, you should always style it as "MongoDB", not "Mongodb" or "Mongo"
• Keep it short: some words may "feel" more technical but there's often a shorter, more familiar word that would make a better substitute. For example, "utilize" can almost always be replaced with "use"

If the word or phrase in question isn't covered in this guide or in the Google developer documentation style guide's Word List, don't hesitate to ask the folks in the #docs Slack channel - we nerd out about this stuff. We also encourage you to refer to the other resources found in the Style Guide.