Wiki Writing Style

Owned by Kythera of Anevern
Last updated: Oct 08, 2020
4 min read

This page outlines the writing style and guidelines for the QA wiki.

PORTFOLIO NOTE
This guide was originally created based on the interface of a server-based Confluence space, rather than a cloud-based space. The interfaces have significant differences.

Please note that identifying company information and non-generic page titles have been redacted throughout this article.

On this page:

Basic Grammar and Style

  • Serial comma: YES. Rare is the occasion where it is not used. "A comma used to separate the second-to-last item in a list from a final item introduced by the conjunction and or or" (e.g. an Italian painter, sculptor, and architect)

  • Spacing after terminal punctuation: Use a single space after terminal punctuation before starting a new sentence. Grammar Underground has a good explanation for why this is standard.

  • Headings: Follow title capitalization rules. If in doubt, use https://capitalizemytitle.com/.

  • Numbers: Spell out numbers one through ten. Use numerals for numbers greater than ten.

    • Examples: "You can have up to five ships in your fleet." "There are 150 different widgets."

  • Acronyms and abbreviations: The first time an acronym or abbreviation is used on a page, spell it out, then follow it immediately with the acronym or abbreviation in parentheses (e.g. "Check the current Test Plan (TP)."). The acronym or abbreviation can then be used throughout the rest of the page.

  • Punctuation and quotation marks: There are a few guidelines to follow when it comes to quoted text and punctuation:

    • Per the Chicago Manual of Style, place commas and periods inside quotation marks when quoting text.

      • Examples: She said, "I'll be there soon." "When you are finished," he said, "we'll leave."1

    • Question marks and exclamation points should be placed outside of quotation marks, unless they are part of the text being quoted.

      • Examples: "Lend me your ears!" I need to finish this "yesterday"!

  • Non-English words: Italicize non-English words and abbreviations of non-English words, such as e.g. and i.e.

  • Writing style: Keep the writing style of entries impersonal; avoid letting opinions or judgments (e.g. words like "just" or "simply") slip in to the writing.

  • Active voice: Write using the active voice:

    • Active voice: "Double-click on the widget.exe file to launch the Widget Program."

    • Passive voice: "Double-clicking on the widget.exe file will launch the Widget Program."

  • Humor: Humor is acceptable (we are a game company, fun is our job), but easy to abuse. It is best when used sparingly.

Spelling

Chrome and Firefox have built-in spellcheck functionality. If in doubt about how to spell a word, look to game-specific style guides and glossaries for game terms, and Merriam-Webster for all other English spelling questions.

Common Terms

This is an index of the correct spelling/capitalization for various terms commonly used in the wiki:

  • Company Name: This entry will contain links to any legal and/or marketing materials that outline how to correctly style the name of the company, and any associated logos or terminology.

  • VampYre: Proper noun; capital V, capital Y

  • JIRA: All-caps

  • Scrum: Proper noun, always capitalized (but not all-caps) 

Quoted Text

When quoting text, especially in-game text, quote the text exactly as it appears on-screen. When quoting on-screen text, place any terminal punctuation (including periods and commas) that is not part of the on-screen text outside the quotation marks. This breaks normal grammar rules (periods and quotations marks are always placed inside quotation marks, exclamation points and question marks outside quotation marks), it prevents the reader from mistaking the punctuation as part of the quoted text.

Example Text

In order to set a block of example text off from the rest of the wiki entry, use the Quote formatting style. It will make the example look like this (this example is from the Writing Compliance Bugs entry):

Summary: [TRC R4018] UI - No animation during initial loading screen.

Labels: TRC UI LOADING

Severity: A

Description:

DESCRIPTION
The initial loading screen is longer than 30 seconds and does not contain any animation. This can look like the game has locked up to the end user.

STEPS
1. Launch the game on PS4.
2. Use a stopwatch to find the length of time the "Loading" screen is shown without animation.

To apply a formatting style to text, select the text, then click on the Paragraph option in the editing toolbar and select the desired format from the drop-down menu.

Relying only on bolded text or heading styles when using a large block of example text can make the text look like a continuation of the wiki article under a new heading, rather than an example.

Lists

Bulleted or numbered lists can help set correlated chunks of information apart from the surrounding text, such as a group of definitions. An example of using a bulleted list to "chunk" text would be:

This example is from a bug format wiki page

Use additional text formatting within entries in a list if it will improve readability or clarity. For example, if it's a bulleted list of definitions, consider bolding the words being defined:

  • TDM: Team Death Match

  • q'd: HipChat shorthand for "queued"

Consider also using colons rather than dashes between the term and its definition. Per Merriam-Webster's Guide to Punctuation and Style, "A colon introduces a clause or phrase that explains, illustrates, amplifies, or restates what has gone before."

If the list is for a series of steps, use numbers rather than bullets. For example:

  1. Start the game

  2. The next step in the process

  3. Etc.

Debug Code, Programming Code, or Other User-Entered Text

When including examples of debug code or other user-entered text that is in-line with descriptive text, use the Noformat macro. For example:

To hide all warnings/debug text, open the console and type:

DisableAllScreenMessages

Then press Enter.

Using this format is especially important when listing programming or scripting code, since some of the symbols used in programming code can be interpreted as wiki markup by Confluence, thus affecting the formatting of the page and the way the code is displayed to the user.

Footnotes

1. http://editingandwritingservices.com/commas-periods-inside-or-outside-quotation-marks/