github.com/Racer159/jackal@v0.32.7-0.20240401174413-0bd2339e4f2e/docs/12-contribute-to-jackal/4-style-guide.md (about)

     1  # Jackal Documentation Style Guide
     2  
     3  ### Introduction
     4  Welcome to the Defense Unicorns Project Documentation Style Guide, your guide to writing style and terminology for all project communication. This style guide provides editorial guidelines for writing clear and consistent Unicorn-related documentation. Writing is an essential aspect of open-source software development, including documentation, user guides, and communication with the community. Consistency and clarity are critical in conveying our information effectively.
     5  
     6  ### Writing Goals
     7  With every piece of content or documentation we publish, we should aim to:
     8  - **Be clear:** Start with the key takeaway. Put the most important thing in the most noticeable spot. Make choices and next steps obvious. Give people just enough information to make decisions confidently.
     9  - **Be concise:** Everyone likes clarity and getting to the point. Break it up. Step it out. Layer. Short sentences and fragments are easier to scan and read.
    10  - **Be useful:** Before you start writing, ask yourself: What purpose does this serve? Who is going to read it? What do they need to know?
    11  
    12  ### Writing Tone
    13  Here at Defense Unicorns, we aim to publish project documentation that is informative and approachable. It should convey a sense of reliability and expertise while also being easy to understand to those who read our project documentation. The tone should be educative and welcoming, highlighting the benefits and features of our software in a clear and concise manor.
    14  
    15  Here are some key elements of writing in the Defense Unicorn tone:
    16  - Use [active voice](https://webapps.towson.edu/ows/activepass.htm), avoid using passive voice.
    17  - Write plainly, avoid using cliches, colloquiums, jargon, and unclear analogies.
    18  - Be crisp and clear, make it simple.
    19  - Be warm and relaxed, we're humans!
    20  - Be technically correct.
    21  
    22  ### Capitalization
    23  Defense Unicorns style uses sentence-style capitalization. That means everything is lowercase except the first word and proper nouns, which include the names of brands, products, and services.
    24  
    25  Follow these guidelines for creating Defense Unicorns content:
    26  
    27  #### Body Style Capitalization:
    28  - Use sentence-style capitalization for all body text.
    29     - Capitalize the first word of a sentence, heading, title, or label.
    30     - Capitalize proper nouns and Defense Unicorn products.
    31        - Jackal/Big Bang/K8s/K9s
    32  - When words are joined by a slash, capitalize the word after the slash if the word before it is capitalized.
    33  
    34  #### Title/Heading Style Capitalization:
    35  - Use title case.
    36     - 'Connect to the Internet'
    37  - Don't capitalize *a, an,* or *the* unless it's the first word.
    38     - 'The Utility Cluster' 'Jackal is the Best'
    39  - Don't capitalize prepositions of four or fewer letters.
    40     - Such as: *on, to, in, up, down, of, for, yet, but, or,* or *so*
    41  
    42  #### List Style Capitalization:
    43  - Capitalize the first word following a bullet or numbered list.
    44  
    45  #### Colon Style Capitalization:
    46  - Use a lowercase letter to begin the first word of the text immediately following a colon, unless the text is one of the following:
    47     - A Proper noun.
    48     - A heading.
    49     - A quotation.
    50     - Text that follows admonitions such as *Note* or *Tip*.
    51  
    52  ### Code Examples
    53  Many developers copy example code from documentation into their own code or adapt code examples to their own needs.
    54  
    55  To create useful code examples, identify tasks and scenarios that are meaningful for your audience, and then create examples that illustrate those scenarios. Code examples that demonstrate product features are useful only when they address the problems that developers are trying to solve.
    56  
    57  Follow these guidelines for creating Defense Unicorns code examples:
    58  * Create concise examples that exemplify key development tasks. Start with simple examples and build up the complexity after you cover common scenarios.
    59  * Create code examples that are easy to scan and understand. Reserve complicated examples for tutorials, where you can provide a step-by-step explanation of how the example works.
    60  * Add an introduction to describe the scenario and explain anything that might not be clear from the code. List the requirements and dependencies for using or running the example.
    61  * Provide an easy way for developers to copy and run the code. Ideally a copy button in the code block itself.
    62  * Show expected output, either in a separate section after the code example or by using code comments within the code example.
    63  
    64  ### Text Formatting
    65  The thoughtful use of fonts, text formatting, capitalization, alignment, and spacing creates a first impression, reinforces the Defense Unicorn brand, and improves readability. The consistent formatting of text elements, such as command names and URLs, reduces ambiguity and helps users find and interpret information easily.
    66  
    67  Follow these guidelines for creating proper Defense Unicorns text formatting:
    68  
    69  * Use headings to show hierarchy of information.
    70  * Project documentation and project websites use Roboto for the body text, unless explicitly stated in otherwise in the project brand guide.
    71  * When referring to bold formatting, use bold.
    72  * When referring to italic formatting, use italic.
    73  * Default to using left alignment for all body text and titles in documentation.
    74    * Titles may be center aligned on websites and marketing materials.
    75  
    76  ### Procedures and Instructions
    77  It is important to ensure that our communication is clear, concise, and useful. Many portions of our documentation consists of examples and tutorials for users to deploy our software. Creating consistent formatting helps users locate and interpret steps and procedures efficiently.
    78  
    79  Follow these guidelines for creating Defense Unicorn instructions and procedures:
    80  
    81  * Format procedures consistently so customers can find them easily by scanning.
    82  * Consider using a heading to help users find instructions quickly.
    83  * Use complete sentences.
    84  * Capitalize the first word in each step.
    85  * Use a period after each step.
    86  * Use a period after each bullet or list item.
    87  
    88  ### Grammar Rules
    89  Adhering to certain rules of grammar and mechanics helps us keep our writing clear and consistent. It's important to ensure that content grammar and mechanics align with our company's values of sharing insights and mission impact.
    90  
    91  Following these guidelines will help you write content and documentation that is informative and approachable:
    92  
    93  * Use the Oxford comma.
    94  * Avoid run-on sentences.
    95  * Use commas appropriately.
    96  * Use active voice.
    97  * Avoid using exclamation points in text except when they're part of a code example.
    98    * Rather than using exclamation points to call attention to an important point, consider using notices such as Note or Caution.
    99    * See the 'Admonitions' section.
   100  
   101  ### Heading and Title Language
   102  Considering the majority of our documentation revolves around Jackal, it's components, and commands, the language we use to introduce titles and headings needs to reflect the correct tense.
   103  
   104  **Default to using the tense of the command when addressing it in titles and headings.** For example:
   105  
   106  * "Create Package"/"Package Create"
   107  * "Deploy Package"/"Package Deploy"
   108  * "Package Publish"
   109  
   110  **Do not use:**
   111  
   112  * "Package Creation"
   113  * "Package Deployment"
   114  * "Package Publication"
   115  
   116  A good rule of thumb for creating titles and headings is to ensure that they do not wrap on the right hand side of the documentation. This is to maintain consistency and ease of use for the reader.
   117  
   118  ### Abbreviations
   119  Abbreviations are commonly used in the industries we work in (Technology, Defense, Government/Civilian). Abbreviations may be a more effective way of communicating information, especially when the abbreviation is used as a proper noun (ex. DoD, DevSecOps). Remember that some readers may not know what an abbreviation means, especially if it is industry specific.
   120  
   121  #### When to use Abbreviations
   122  Abbreviations are intended to save the writer and the reader time. If the reader has to think about an abbreviation, it can slow down their reading comprehension.
   123  
   124  To avoid confusion and ensure understanding for all users, follow these guidelines when using abbreviations:
   125  
   126  * Spell out abbreviations the first time you use them on a page or in a document with the abbreviation in parenthesis following the definition.
   127    * Ex. Continuous Integration & Continuous Delivery (CI/CD)
   128  * Capitalization of abbreviation follow the capitalization of each letter used when spelled out.
   129    * Ex. Department of Defense is abbreviated to DoD
   130  * Use standard acronyms and initialisms that will save the reader time.
   131  * Spell out abbreviations on first reference, be sure to include the abbreviation in parenthesis following the definition.
   132  * Avoid using abbreviations for terms that aren't related to the main topic of the document.
   133  * Do not use period (.) between letters.
   134  
   135  #### Common Abbreviations
   136  **Technology**
   137  * Continuous Integration & Continuous Delivery (CI/CD)
   138  * Development Security & Operations (DevSecOps)
   139  * Kubernetes (K8s)
   140  * Software Bill of Materials (SBOM)
   141  * Command Line Interface (CLI)
   142  
   143  **Defense**
   144  * Department of Defense (DoD)
   145  * Continuous Authority to Operate (cATO)
   146  * Government/Civilian (Gov/Civ)
   147  
   148  ### Admonitions
   149  A footnote is an annotation with additional information usually provided at the end of a page. Footnotes can provide the reader with more insight, or warn them of a possible caveat. For our documentation, we will be using [Docusaurus admonitions](https://docusaurus.io/docs/markdown-features/admonitions) to populate footnotes.
   150  
   151  Use *Note* when: you need to provide additional insight on the main text that could be one-off or situational.
   152  
   153  Use *Tip* when: there may be additional information that could improve the process or help complete a task.
   154  
   155  Use *Info* when: you need to include additional information that would disrupt the flow of the main text.
   156  
   157  Use *Caution* when: you need to highlight something critical or important.
   158  
   159  ### Linking Text
   160  Linking to other forms of documentation or references is a great way to provide additional insight to the reader. In general, cross-references or in text links can provide information that adds to the reader's understanding.
   161  
   162  Follow these guidelines to efficiently link the reader to other resources:
   163  
   164  * To write link text, use descriptive phrases that provide context for the material that you're linking to.
   165    * "For more information on what Jackal consists of, see [Jackal Packages](../3-create-a-jackal-package/1-jackal-packages.md).
   166  * When you write a complete sentence that refers the reader to another topic, introduce the link with the phrase For more information, see or For more information about..., see.
   167     * "For more information, see [Getting Started](../1-getting-started/index.md)."
   168  
   169  When linking text, **avoid** using non-descriptive terms as the text. Using text such as "here" or "see more" can depreciate the usability for readers. For example, do **not** say:
   170  * "For more information, see [here.]"
   171  * "You can also try out the component actions example [here.]"
   172  
   173  ### Jargon
   174  Jargon is the specialized and often figurative terminology of a specific group to represent a larger concept—for example, camel case, swim lane, break-glass procedure, or out-of-the-box. Typically, the meaning of jargon isn't understood except by the specific group. For this reason, jargon can hamper our efforts to publish content that's clear.
   175  
   176  However, some jargon is widely understood and accepted by our industry or by the intended audience of a document. It can be valuable to include jargon in a document when you know that readers search for those terms.
   177  
   178  Don't use jargon if:
   179  
   180  * You can use a more familiar term, such as symbol instead of glyph.
   181  * The term is familiar to only a small segment of your readers.
   182  * The term isn't specific to software, networking, cloud services, and so on.
   183  
   184  If you're going to use jargon, consider the following questions:
   185  * **Can you write around the term?** If you don't need the term for search engine optimization (SEO), try writing around it. For example, instead of writing Hold a post-mortem, write When the project is finished, review what processes worked or didn't work. Instead of writing Create a back-of-the-envelope design, write Use an informal design process.
   186  * **Are you using the term only once in your document?** If so, describe the term in plain language and refer to it in parentheses, or link to a trusted definition.
   187  * **Are you using the term throughout your document?** If so, briefly describe the term in parentheses on first reference, or link to a trusted definition.
   188  
   189  ### Word List
   190  Follow these guidelines for standardizing Defense Unicorn's spelling and grammar:
   191  
   192  * Jackal
   193  * Jackal Package
   194  * Open-source
   195  * Air gap/Air-gapped
   196  * K8s
   197  * K9s
   198  * K3d
   199  * K3s
   200  * High side/Low side