The Bottlerocket content style largely follows the OpenStack General Writing Guidelines.
Take the time to read through the OpenStack General Writing Guidelines and adapt these appropriately to the context of Bottlerocket as needed. At a high level, these guidelines state that you should write in:
Copyright and licensing
Bottlerocket’s copyright and licensing information can be found in files with the prefix LICENSE in the root of each repo.
Collective Pronouns The OpenStack General Writing Guidelines take a “judicious” approach to the use of the first person plural pronouns of we and our. Counter to the instruction in that writing guide, “we”/“our” should not be used as a stand-in when writing for Bottlerocket, contributors, nor a particular team. In the context of Bottlerocket, use only “we”/“our” for collective works with two or more explicitly stated authors. This change is needed to provide extra clarity to readers regarding decision making given the current structure of Bottlerocket.
Inclusive Terms Avoid terms on Inclusive Naming’s Tier 1, Tier 2, and Tier 3 lists.
Consider the Markdown documents used as website content to be precursors to the final rendered website, not a final product on their own. While Markdown does somewhat isolate the style from the content, the limited nature of the Markdown markup doesn’t allow for precise control without some impact on the structures. All document conventions serve first the desired rendered output over any other demands.
Additional conventions:
- Use CommonMark spec markdown
- One sentence-per line, ending with a carriage return.
- Double carriage return for paragraph endings
- Use real-numbering for lists
- Backticked inline code should limited to 60 characters, otherwise use code blocks (triple backtick)
- Images must include alt text, while title text is optional.
- Captions to images should be included as italics text immediately following the image markup.