Skip to content
Zarf

Documentation Style Guide

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.

With every piece of content or documentation we publish, we should aim to:

  • 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.
  • 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.
  • 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?

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.

Here are some key elements of writing in the Defense Unicorn tone:

  • Use active voice, avoid using passive voice.
  • Write plainly, avoid using cliches, colloquiums, jargon, and unclear analogies.
  • Be crisp and clear, make it simple.
  • Be warm and relaxed, we’re humans!
  • Be technically correct.

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.

Follow these guidelines for creating Defense Unicorns content:

  • Use sentence-style capitalization for all body text.
    • Capitalize the first word of a sentence, heading, title, or label.
    • Capitalize proper nouns
      • Zarf/K8s/K9s
  • When words are joined by a slash, capitalize the word after the slash if the word before it is capitalized.

  • Use title case.
    • ‘Connect to the Internet’
  • Don’t capitalize a, an, or the unless it’s the first word.
    • ‘The Utility Cluster’ ‘Zarf is the Best’
  • Don’t capitalize prepositions of four or fewer letters.
    • Such as: on, to, in, up, down, of, for, yet, but, or, or so

  • Capitalize the first word following a bullet or numbered list.

  • Use a lowercase letter to begin the first word of the text immediately following a colon, unless the text is one of the following:
    • A Proper noun.
    • A heading.
    • A quotation.
    • Text that follows admonitions such as Note or Tip.

Many developers copy example code from documentation into their own code or adapt code examples to their own needs.

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.

Follow these guidelines for creating Defense Unicorns code examples:

  • Create concise examples that exemplify key development tasks. Start with simple examples and build up the complexity after you cover common scenarios.
  • 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.
  • 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.
  • Provide an easy way for developers to copy and run the code. Ideally a copy button in the code block itself.
  • Show expected output, either in a separate section after the code example or by using code comments within the code example.

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.

Follow these guidelines for creating proper Defense Unicorns text formatting:

  • Use headings to show hierarchy of information.
  • Project documentation and project websites use Roboto for the body text, unless explicitly stated in otherwise in the project brand guide.
  • When referring to bold formatting, use bold.
  • When referring to italic formatting, use italic.
  • Default to using left alignment for all body text and titles in documentation.
    • Titles may be center aligned on websites and marketing materials.

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.

Follow these guidelines for creating Defense Unicorn instructions and procedures:

  • Format procedures consistently so customers can find them easily by scanning.
  • Consider using a heading to help users find instructions quickly.
  • Use complete sentences.
  • Capitalize the first word in each step.
  • Use a period after each step.
  • Use a period after each bullet or list item.

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.

Following these guidelines will help you write content and documentation that is informative and approachable:

  • Use the Oxford comma.
  • Avoid run-on sentences.
  • Use commas appropriately.
  • Use active voice.
  • Avoid using exclamation points in text except when they’re part of a code example.
    • Rather than using exclamation points to call attention to an important point, consider using notices such as Note or Caution.
    • See the ‘Admonitions’ section.

Considering the majority of our documentation revolves around Zarf, it’s components, and commands, the language we use to introduce titles and headings needs to reflect the correct tense.

Default to using the tense of the command when addressing it in titles and headings. For example:

  • “Create Package”/“Package Create"
  • "Deploy Package”/“Package Deploy"
  • "Package Publish”

Do not use:

  • “Package Creation"
  • "Package Deployment"
  • "Package Publication”

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.

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.

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.

To avoid confusion and ensure understanding for all users, follow these guidelines when using abbreviations:

  • Spell out abbreviations the first time you use them on a page or in a document with the abbreviation in parenthesis following the definition.
    • Ex. Continuous Integration & Continuous Delivery (CI/CD)
  • Capitalization of abbreviation follow the capitalization of each letter used when spelled out.
    • Ex. Department of Defense is abbreviated to DoD
  • Use standard acronyms and initialisms that will save the reader time.
  • Spell out abbreviations on first reference, be sure to include the abbreviation in parenthesis following the definition.
  • Avoid using abbreviations for terms that aren’t related to the main topic of the document.
  • Do not use period (.) between letters.

Technology

  • Continuous Integration & Continuous Delivery (CI/CD)
  • Development Security & Operations (DevSecOps)
  • Kubernetes (K8s)
  • Software Bill of Materials (SBOM)
  • Command Line Interface (CLI)

Defense

  • Department of Defense (DoD)
  • Continuous Authority to Operate (cATO)
  • Government/Civilian (Gov/Civ)

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 to populate footnotes.

Use Note when: you need to provide additional insight on the main text that could be one-off or situational.

Use Tip when: there may be additional information that could improve the process or help complete a task.

Use Info when: you need to include additional information that would disrupt the flow of the main text.

Use Caution when: you need to highlight something critical or important.

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.

Follow these guidelines to efficiently link the reader to other resources:

  • To write link text, use descriptive phrases that provide context for the material that you’re linking to.
    • ”For more information on what Zarf consists of, see Zarf Packages.
  • 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.

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:

  • “For more information, see [here.]"
  • "You can also try out the component actions example [here.]”

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.

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.

Don’t use jargon if:

  • You can use a more familiar term, such as symbol instead of glyph.
  • The term is familiar to only a small segment of your readers.
  • The term isn’t specific to software, networking, cloud services, and so on.

If you’re going to use jargon, consider the following questions:

  • 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.
  • 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.
  • 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.