Wiki Page Elements

This page provides descriptions and instructions for when and how different elements of wiki pages are used.

On this page:

Page Layout

Sections

Pages are laid out in sections, using the "Two column section with right sidebar" style. This format is used to create optimum readability for wiki pages.

Page content is placed in the left column. The right column is reserved as white space, and for "^ top of page" links. In rare instances, annotations may be placed in the right column. All other content goes in the left column.

Headings

Use title capitalization rules for headings (any text that will have one of the various heading styles applied to it). Omit periods and colons, and use exclamation points or question marks sparingly. Small words, such as a, an, the, but, and, if, as, or, nor, etc. are not capitalized, unless they are the first or last word in the title. Hyphenated terms in headings will be treated according to Chicago Manual of Style 15 8.170¹.

Examples of headings:

Open

When to Use Headings

Use headings at the start of a new section, or to highlight important information within a section. Main headings, such as the "Overview" at the beginning of each page, should use the Heading 2 style. The Heading 1 style is almost indistinguishable from the format of page titles, so it is not used.

As a general rule, each section has only one heading. Sub-sections, which would use a Heading 3 (or higher) format, are placed in a new section, immediately below their parent section. Below is how the Info, Tip, Note, and Warning Macros section and sub-sections of this page appear in the page editor.

Open

Images

When inserting images, place a border around it to set it off from the rest of the page. This is especially important when the image has a white or light-colored background. Compare these two
examples:

The image with the border stands out more clearly as an inserted image, rather than an element of the wiki page.

To place a border around an image, insert the image into the text, click on the inserted image, then click on the Border button to toggle the border on or off.

Image Captions

Confluence lacks a method of generating a caption that appears below an image. The following steps are the current best practice for adding a caption to an image.

1. Insert a 1 x 2 table using the Insert table button in the editor toolbar.

    

2. Insert the desired image into the top cell of the table (a cat picture is used for this example).

3. Type the caption in the bottom cell of the table.

4. Italicize the caption text.

Useful Macros

Status

The status macro generates a small colored box that contains user-entered text. It is a useful way to draw attention to important text, such as the number rating in a list of testing risks.

These are examples of the available colors:

example example example example example

This is an example of status macros used in (a redacted) Risk Assessment to emphasize the severity of risk ratings:

Insert "Status" Macro

1. Type {status and press Enter to open the Insert 'Status' Macro modal.

    

2. Type desired text for the macro in the Title field of the "Insert 'Status' Macro" modal.

3. Select the desired color from the drop-down.

4. If you want an outline style macro, check the "Use outline style" box.

5. Click the Preview icon to refresh the preview image of the macro.

6. Click Insert to insert the macro when you are satisfied with how it looks.

Edit "Status" Macro

There are two ways to edit an existing status macro in the page editor:

1. To edit an existing status macro, double-click on the status macro to open the Insert 'Status' Macro modal.

2. Click on the status macro you want to edit to open a quick edit toolbar.

• Click the Edit button to open the full status macro editor.

• Change the text of the macro using the text entry field (it contains the text "EXAMPLE" in the above screenshot).

• Change the color by clicking the corresponding color button.

• Click the Remove button to remove the macro entirely.

Info, Tip, Note, and Warning

Info, Tip, Note, and Warning macros are helpful for setting off important information from the surrounding text. See the Info, Tip, Note, and Warning Macros page for detailed information on how to use these macros. Examples of the macros in use are shown below.

Info

From the (Redacted) page:

Logs and Dump files are both located in the same folder, which changes based on the executable used.

Server files require a request from department QA Leads or the Tech team.

Tip

From the (Redacted) page:

This page details the process for awarding XP in (the game). Note that this can only be done in testing builds, and that awarding XP on the live servers for testing requires Production approval.

Note

From the PS4 Bug Format page:

Video clips are saved into the capture gallery the same way as a screenshot is saved. When you save a video clip, however, the video is save retroactively. For example, depending on your capture gallery settings, selecting save video clip will save the 3 minutes of gameplay on your screen BEFORE you selected "save video clip". This is different from saving a video through Fraps where you must start recording before you reproduce the bug.

To do this, select the chosen video clip. Then, select the Options button. This will bring you to the Trim Screen. You can Trim your video in intervals of a selected amount of seconds. Use the left stick and X to select where you wish the video to begin and end.

Once you have selected how you wish your video to be trimmed, select "OK" to save trim.

Warning

From the PS4 Bug Format page:

Unlike the PC, evidence for bugs must be transferred from the console to the PC physically using a USB drive. USB drives can be obtained from a PS4 lead. 

Labels

Add appropriate labels to each page. Adding labels to a page helps group related pages together and make related pages easier to find. Try to only use existing labels if possible (a complete list of the labels currently in use can be found here). Look at other related pages to see what labels they use. If a new label is necessary, try to keep it short and simple (one word only), but descriptive; think of what the page might be listed under in the index of a printed book.

Labels can be added to a page in the process of being created or edited by clicking the Labels icon next to the page title:

Labels can be added to an existing page by clicking the pencil icon in the bottom right corner of the page:

Date

To add a neatly formatted date (Jul 2, 2018) to a wiki page:

1. Type two forward slashes.

   • Example:

     //

2. This opens a calendar modal that allows you to select a date.

3. Use the < and > arrows to select the month

4. Click on the date to add it to the page

   • Example: Jul 2, 2018 

^ Top of Page

If a page is very long (e.g. contains three or more sections), add "^ top of page" link at the bottom of each section. This allows a user to return to the table of contents and jump directly to another
section of the page if they wish. The horizontal line at the end of each section helps to visually separate and "chunk" a large quantity of sections.

There is no dedicated macro for creating a "^ top of page" link, so it has to be created manually.

1. Insert an anchor macro at the very top of the page, before the "Overview" heading

2. On a new line after the last word of text, type three dashes to create a horizontal line.

   • Example: 

     ---

3. Below the horizontal line, create a link to the anchor you created at the top of the page; the link text should be "^ top of page".

4. The "^ top of page" link can be copied and pasted multiple times on the same page without having to repeat the above steps for each link.

Footnotes

1. CMS 15 8.170: “Hyphenation: The more traditional rules. (1) Always capitalize the first element. (2) Capitalize any subsequent elements unless they are articles, prepositions, coordinating conjunctions (and, but, for, or, nor) or such modifiers as flat or sharp following musical key symbols. (3) If the first element is merely a prefix or combining form that could not stand by itself as a word (anti, pre, etc.), do not capitalize the second element unless it is a proper noun or proper adjective. (4) Do not capitalize the second element in a hyphenated spelled-out number (twenty-one, etc.). (5) Break a rule when it doesn't work."