Writing style guidelines

Keep Codewind documentation consistent with correct grammar and proper formatting. These style guidelines apply to Codewind documentation, including guides and tutorials.

Accessibility

• To test content for accessibility, use the Dynamic Assessment Plugin (DAP) tool in Google Chrome.
• Add alt text to screenshots for readers who use screen readers. For information on formatting images, see Images guidelines.
• Avoid sight-related words when writing instructions.
  • Avoid directional words when referring to the UI, such as "Click the button below."
  • Avoid mentioning colors, such as "Click the blue button."

Heading and titles

• Use sentence case. Capitalize only the first word and proper nouns in titles and headings.
• Begin titles and headings with a gerund, such as "Installing" or "Creating."
• Avoid the ambiguous word "using" in a title or heading. "Using" can refer to many different tasks.
• Headings are formatted based on basic Markdown: https://www.markdownguide.org/basic-syntax/
  • Use # for titles like the name of the page.
  • Use ## for subheadings.
  • Use ### for further subdivision.
  • Try to avoid #### and any smaller heading.

Body text formatting

Acronyms

• The first time you use an acronym in a document, write out what the acronym stands for followed by the acronym in parenthesis.
  • Example: "Software as a service (SaaS)"
• If the acronym is commonly used, and your audience is already familiar with it, you don't need to write out what it stands for.
  • Example: "HTML"
• Remember that some acronyms could have more than one meaning, so you might want to clarify even if they're commonly used.

Adding notes

• Follow this format when creating a note: **Note:**
  • Make it bold.
  • Include the colon inside the bold formatting.
  • Capitalize the first word after the word "Note."
  • Example: "Note: Install the latest version of Codewind."
• Other notations like Important:, Optional:, and Caution: should be formatted like Note:.
  • Use Caution: to alert the user to proceed with caution and explain why the user should exercise caution. See Error appears after installing or updating Codewind for an example of a Caution note.
  • We shouldn't need to use Warning:. It implies a greater level of danger.

Arrows

• Use arrows when indicating navigation menu items.
  • Example: Click **Documents**>**GitHub**>**codewind-docs**.
• Do not use arrows for lists of actions. Use commas like you would in any other list.
  • Example: "Enter your changes, save your file, and open a new window."

Bold

• Use bold for button names, UI elements.
• Don't include punctuation as part of bolded words unless the punctuation is part of the name.
  • Example: If a button is named Open File, don't make any surrounding punctuation bold because the punctuation is not part of the button name.
• The project name "Codewind" should not be bold unless referring to a UI element.

Code phrase format

• Use code phrase format for text, commands, or lines of code that the user needs to enter.
• Also use code phrase format for file names and file paths.
• Don't include punctuation inside of code phrase formatting unless the punctuation mark is part of the code itself.
  • Users want to quickly and easy distinguish code from surrounding text so they can copy and paste it into their command lines.
  • Extra punctuation marks can make code unusable.
  • Example 1: "To commit your changes in GitHub, enter git commit -s -m "note on changes"."
  • Example 2: "To commit your changes in GitHub, enter the git commit -s -m "note on changes" command."

Images

• Don't break a sentence with a big screenshot. Use shorter sentences to precede a screenshot instead of a longer sentence that spans multiple screenshots.
• For information on formatting images, see Images guidelines.

Linking

• Use linked text instead of a URL.
• When linking a file, use its title as the hyperlink.
• Examples:
  • ✅"For more information, see Installing Codewind for Eclipse."
  • 🚫"For more information, see https://www.eclipse.org/codewind/mdt-eclipse-installinfo.html."

Lists

• Use unordered, bulleted lists for items of equal importance and for items that do not need to be performed in a specific order.
  • Unordered lists are probably good for listing projects or team member names.
  • List the items in alphabetical order.
  • Make unordered lists parallel if possible. For example, make all items in the list complete sentences or make all items a noun + a prepositional phrase.
• Use numbered, ordered lists for items that require a specific order, such as instructions. 

Other body formatting

• Avoid using italics for emphasis because of the similarity of italics with surrounding "normal" text.

Mood

• Be positive.
  • Don't focus on limitations.
  • Simply state the facts.
• When writing instructions, use imperative mood. This mood gives a command.
  • Examples:
    • ✅"Open the browser of your choice."
    • 🚫"You can open the browser of your choice."
    • ✅"Change the background color with the Background button."
    • 🚫"You can change the background color with the Background button."
• Explain the purpose of an action before stating the action itself.
  • Examples:
    • ✅"To install the software, first open the software marketplace page."
    • 🚫"First open the software marketplace page to install the software."
• Refrain from adding "please" before imperative sentences in instructional documentation.

Parenthesis

• Other than acronyms, avoid parenthesis. Parenthesis indicate content is less important, inviting readers to gloss over it. When considering parenthesis, ask yourself if you should include the parenthetical content in the first place.

Pronouns

• Avoid first person pronouns (I/me/we/us) in instructional documentation.
  • If the written content doesn't have a listed author, it's unclear to the reader who the pronoun refers to. Is it Codewind developers? The author of the page? Someone else?
  • However, first person pronouns work well for blogs, which include an author's name.
• Use the second person "you" to address the user instead of using third person and referring to users as "the users" or "the developers."
  • If you can avoid a pronoun altogether and use an imperative instead, that's even better.

Special characters:

• Avoid subscripts and superscripts unless you need to include mathematical equations in your text.
• The / character can be a bit ambiguous. Use "or" or "and" instead.
  • ✅"Choose local or remote Codewind."
  • 🚫"Choose local/remote Codewind."

Punctuation

Colons

• Use a colon to introduce a code block, graphic, or list.
• A colon should generally end a complete sentence.
• Examples:
  • ✅"The following chart shows the release dates for the year:"
  • 🚫"Release date chart:"

Commas

• Use the Oxford comma. When you have three or more items in a series, add a comma after the last item and before the conjunction.
  • ✅"Appsody, Codewind, and Open Liberty are open source projects."
  • 🚫"Appsody, Codewind and Open Liberty are open source projects."
• Use commas to surround nonessential phrases and clauses.
• Use a comma and a conjunction between two independent clauses.
  • Example (This sentence needs a comma.): "He drafts the document, and she adds her review."
  • Example (This sentence does not need a comma.): "He drafts the first document and reviews the second."

Periods

• Include periods at the end of complete sentences.
• Periods aren't necessary for phrases or for some titles and UI elements. You might notice sentences without periods if you review messages that appear in the UI.
  • Examples:
    • High or growing memory usage that indicates a potential memory leak
    • Modifying the load test
    • Projects stuck in stopped or starting state
• If a list is made of complete sentences, add the periods. If the list is phrases, they don't need periods.

Quotation marks

• Codewind documentation generally shouldn't need quotation marks because you can use bold and code phrase format instead.
• However, if you do need quotation marks, remember to use the American formatting.
  • Start with "double quotation marks" and then use 'single quotation marks' if you need a quotation within a quotation.

Other punctuation

• Keep question marks and exclamation points to the more conversational style of blogs.

Spelling

• Use American spellings.
  • Examples of words that differ according to country: analyze, color, containerized, customized, optimizing, visualize
• Note the capitalization, spacing, and spelling of the following names:
  • GitHub
  • MicroProfile
  • VS Code

Voice

• Use the active voice as much as possible.
• If you need to hide the actor of a sentence, such as to avoid sounding like you're blaming the user for a problem, you can use the passive voice. However, in many cases, you can probably find a way to use the active voice and still avoid blaming the user.
  • Passive: "If a previous version was installed, the program might not load."
  • Active: "Ensure that you install the latest version to load the program."
  • Passive voice is grammatically correct, but use your judgement when deciding on when to use it.

Verb tenses

• Write in the present tense as much as possible.   - Examples:
  • "Click Start to begin the game."
  • "This class teaches the basics of coding."
• Avoid saying anything about potential future functionality and features. The team might be planning to add a certain feature in the next release, but there's always a chance something prevents it from happening. It's safest simply not to say anything about the future.

Writing style

• Be concise, but not at the expense of clarity.
  • Sometimes words like "that" are useful for clarity even if they can be omitted.
• You might also use more words for a more a more friendly, personable tone.
• Use shorter words and phrases when possible.
  • ✅"Delete unused files for more space."
  • 🚫"Delete unused files for additional space."
  • ✅"The latest version can run the software."
  • 🚫"The latest version is able to run the software."
• Keep sentences short. Aim for fewer than 32 words.
• Watch out for adverbs, such as "simply" and "just." Most adverbs are unnecessary.
  • ✅"Enter your credentials in the text field."
  • 🚫"Simply enter your credentials in the text field."
  • ✅"To start a new game, click your avatar."
  • 🚫"To start a new game, just click your avatar."
• Avoid saying "best practice" or "for best results" to highlight a recommended course of action. Instead explain why one option is preferable to another.
  • ✅"For the fastest installation, enter..."
  • 🚫"Best practice: Enter..."
• Ending sentences with a preposition is OK.
• When indicating a possibility, use "might" instead of "may."
  • ✅"If X happens, Y might begin."
  • 🚫"If X happens, Y may begin."
  • "May" is more indicative of permission.
  • Example: "May I use this content in my presentation?"
• When using the word "this," ensure a more specific noun follows it.
  • ✅"This command opens the file."
  • 🚫"This opens the file."
• Click or select?
  • "Click" is good for UI elements that are used on the computer.
  • Avoid "click on."
  • "Select" is good for UI elements that are used on mobile apps on a smart phone or tablet.