UnrealEngineUWP/Engine/Documentation/Source/DocumentationGuidelines/StyleGuide/StyleGuide.INT.udn

Availability:Docs
Title:Epic Games Documentation Style Guide
Crumbs:DocumentationGuidelines
Description:Style guide for creating documentation for Unreal Engine 4.

[TOC(start:2)]

## Documentation Policies

### Document Location and Naming

Documentation source files are stored in Perforce in the Engine/Documentation/Source folder as .udn files. The filename must include a language code specifying what language the document is written in. The file name should be descriptive of the document's contents.
Documents are stored one file per folder making the directory path the identifier for the document. Take care in naming the folders so they are descriptive and intuitive. Try not to duplicate elements in the folder names making up the paths. Duplication in the actual document name is acceptable, and generally preferred.

| Good | Bad |
| --- | --- |
| Materials/Editor/UserGuide | Materials/MaterialEditor/MaterialEditorUserGuide |

For example, the English language version of the **Unreal Editor User Guide** document is named `UnrealEditorUserGuide.INT.udn` and is stored in the `Editor/UserGuide` directory.

In the same way, redundancy should be avoided in the titles of pages whenever possible. As an example, imagine a **Getting Started** section that contains a **Content** section which in turn contains a **Materials** page. In isolation, each of these pages might end up named:

* Getting Started with Unreal Engine
* Getting Started with Content Development
* Getting Started with Material Creation


These names are all perfectly fine, but become redundant when viewed side by side. This is especially problematic when it comes to the breadcrumbs displayed at the top of the page as each of these names will be displayed in succession. It would be much better to use variety in the names so that the name is still descriptive of the page's content, but not redundant when compared to each other.

### Content Chunking

There is often a tendency to lump too much content into a single page. It is better to break the content up into logical chunks and keep individual pages to more reasonable and easily digestible sizes.

An example of this might be the topic of _BlendSpaces_ in Animation. Everything about _BlendSpaces_ - creating them, editing them, using them in Vim Blueprints, etc. - could be put into a single page, but it is preferable to break each of those sub-topics off into their own pages with a general overview page as their parent:

* Blendspaces
	* Creating Blendspaces
	* Editing Blendspaces
	* Using Blendspaces


### Identity and Branding

The names of companies, the engine, games, etc. should be consistent throughout every document. The proper spelling, capitalization, numbering, and punctuation for these are provided below.

* Epic Games, Inc.
* Unreal Engine 3/Unreal Engine 4
* Gears of War/Gears of War 2/Gears of War 3
* Infinity Blade/Infinity Blade 2/Infinity Blade 3
* Fortnite


[REGION:note]
Only use short names (UE3/UE4/GoW/IBD) after previously defining them on the page, e.g. Unreal Engine 4 (UE4).
[/REGION]

### Types

When discussing data types - class names, asset types, etc. - always use the correct capitalization to match the type definition. This helps to avoid confusion between a specific type within Unreal Engine and more generic usage of certain words. Also, use italic text with these names to denote they are special.

For example:

| Correct | Incorrect |
| ------- | --------- |
| _Actor_ | actor |
| _Material_ | material |
| _StaticMesh_ or _Static Mesh_ | staticmesh or static mesh |
| _ParticleSystem_ or _Particle System_ | particlesystem or particle system |

### UI Elements

Specific parts of the user interface, such as the **Content Browser** or **Scene Outliner**, should use appropriate capitalization and be displayed in bold.

[REGION:tip]
	Some panels are referred to by their names with "panel" following - the **Details** panel, for example - but the "panel" portion is not capitalized or emboldened. The only exception to this would be if "Panel" was displayed in the UI as part of the name of a window, panel, or other part of the interface.
[/REGION]

| Correct | Incorrect |
| ------- | --------- |
| **Content Browser** | Content Browser or **content browser** |
| **Scene Outliner** | Scene outliner or **scene outliner** 
| **Details** panel | Details panel or **Details Panel** |

## Grammar and Punctuation

### Spacing between sentences

Only one space is necessary between consecutive sentences.

### Commas with Series

Series of items separated by commas should always use a comma preceding the last item in the series. While it is technically valid to leave off the last comma, always using it leaves no room for confusing whether items are separate or part of a set.

| Clear | Ambiguous |
| --- | --- |
| This, that and those, them, and the other one | This, that and those, them and the other |

## Formatting and Layout

### Metadata

All documentation pages are required to have the following metadata:

* Title - the title of the document; displayed in the title bar of the browser and as the level 1 page heading.
* Crumbs - comma separated list of paths to form navigation hierarchy. Each page can have any number of Crumbs metadata entries.
* Description - a short summary; displayed on search results pageMetadata is stored at the top of all source documents as key:value pairs, one per line.


### Headings

Major sections within a document should be denoted using headings (level 2 through 6). 

Headings should always have some text or other content following them before any subheadings. If a heading does not warrant content, consider removing it and reorganizing.

Do not skip levels of headings within the document. For instance, a level 4 heading should never follow a level 2 heading.

#### Page Titles

The page title is inserted into pages automatically and is always denoted using the level 1 heading. This should be the only level 1 heading in any document. Never use a level 1 heading for sections within the document.

#### Capitalization of Headings

Headings should use initial capital letters for all words other than conjunctions (and, or, etc.) and prepositions (to, of, on, etc.). We capitalize all headings the same and rely on proper styling of the different heading levels to distinguish them. 

### Lists

Lists can be ordered, unordered, or definition lists. Unordered lists should always be used for items where the order is not important. Sequential instructions, such as tutorials, should always use ordered lists. Defining specific terms should make use of definition lists.

#### Unordered Lists

Unordered lists should always be created using the '* ' syntax. This makes it immediately obvious when viewing the source where lists are present.

	* unordered item 1
	* unordered item 2
	* unordered item 3
	* unordered item 4

* unordered item 1
* unordered item 2
* unordered item 3
* unordered item 4


While using the '- ' or '+ ' syntax is valid for creating lists, we want to keep uniformity in all documents.

#### Ordered Lists

Ordered can be created by starting a line with any number followed by a period. It is natural to want to number the items 1, 2, 3, 4, 5, etc.; however, each item in an ordered list should always be created using the '1.' syntax.

	1. First item
	1. Second item
	1. Third item
	1. Fourth item

1. First item
1. Second item
1. Third item
1. Fourth item


This makes it easy to insert and reorder the items without needing to worry about the numbering.

#### Defining Items

When defining terms, use definition lists.

Note: For descriptions of properties, menu options, toolbar buttons, etc., tables should be used. See Tables for more information.

### Text Effects

#### Bold and Italics

Bold or strong text should always use the '**' syntax as opposed to the '__' version:

**bold text**

Italic or emphasized text should use the '_' syntax as opposed to the '*' version:

_emphasized text_

When creating bold, italic text, the syntax should be '**_' and '_**':

**_bold emphasized text_**

By keeping with these conventions, there will never be any question about what the intentions of the writer were. It would be very easy for a * or _ to be left off when trying to create bold text or to accidentally add a double ** or __ when meaning to create italic text. If we know that using ** is always bold and _ is always italic, there is no question what formatting the writer meant to add.

### Notes, Tips, Warnings, and Quotes

Special information in the form of notes, tips, or warnings should be set off from other content using the containers for these items. A `<div>` element using the note, tip, or warning class will automatically create a colored box with a special icon around the information within the `<div>`.

#### Note

	[REGION:note]
	This is a note. It is inside a yellow box and you can see the note icon at the top left.
	[/REGION]

[REGION:note]
This is a note. It is inside a yellow box and you can see the note icon at the top left.
[/REGION]
 
#### Tip

	[REGION:tip]
	This is a tip. It is inside a green box and you can see the tip icon at the top left.
	[/REGION]

[REGION:tip]
This is a tip. It is inside a green box and you can see the tip icon at the top left.
[/REGION]
 
#### Warning

	[REGION:warning]
	This is a warning. It is inside a red box and you can see the warning icon at the top left.
	[/REGION]

[REGION:warning]
This is a warning. It is inside a red box and you can see the warning icon at the top left.
[/REGION]
 
#### Quote

	[REGION:quote]
	This is quoted text. It is inside a blue box and you can see the quote icon at the top left.
	[/REGION]

[REGION:quote]
This is quoted text. It is inside a blue box and you can see the quote icon at the top left.
[/REGION]
 
### Images

Images are any graphic displayed within a document.

#### Formats and Resolution 

Use PNG files for source images whenever possible as these are high quality and offer decent file size. 
Author images at the resolution they are to be displayed. If the same image is to be used multiple times 
at different resolutions, author it at the largest resolution it will be displayed at. Resizing on the 
fly generally results in less than desirable quality.

Image sizes:

| Use | Max Image Width |
| --- | -------------- |
| Standard | 720 px |
| Banner | 1180 px |
| Material Networks, Blueprint Graphs | No limit, but should use [lightboxing](#Lightboxing). |

#### Quality

By default, all images are converted to jpeg and compressed. Image quality can sometimes be an issue 
when compressing to jpeg. The [image properties](DocumentationGuidelines/Syntax#ImageProperties) can be used 
to control the compression quality and even override the conversion altogether to use the original 
source image in the published page.

#### Effects

Images should never have any sort of styling or effects. Do not use rounded corners, drop shadows, and other border effects. These will be handled by styles so they can easily be changed as desired without regenerating the source content.

#### Image Tables

It is often useful to display images using tables with the first row containing columns of images and the second row containing captions. Using a normal table will result in some ugliness because of the styles applied. 

	| ![Layers Unfiltered](Engine/UI/LevelEditor/Layers/layer_search_unfiltered.png) | ![Layers Filtered](Engine/UI/LevelEditor/Layers/layer_search_filtered.png) |
	| ------ | ------ |
	| Unfiltered Layer List | Filtered Layer List |

| ![Layers Unfiltered](Engine/UI/LevelEditor/Layers/layer_search_unfiltered.png) | ![Layers Filtered](Engine/UI/LevelEditor/Layers/layer_search_filtered.png) |
| ------ | ------ |
| Unfiltered Layer List | Filtered Layer List |

For this reason, a special _imagetable_ region has been provided. Wrapping the table in one of these regions will result in a much cleaner and more polished look:

	[REGION:imagetable]
	| ![Layers Unfiltered](Engine/UI/LevelEditor/Layers/layer_search_unfiltered.png) | ![Layers Filtered](Engine/UI/LevelEditor/Layers/layer_search_filtered.png) |
	| ------ | ------ |
	| Unfiltered Layer List | Filtered Layer List |
	[/REGION]

[REGION:imagetable]
| ![Layers Unfiltered](Engine/UI/LevelEditor/Layers/layer_search_unfiltered.png) | ![Layers Filtered](Engine/UI/LevelEditor/Layers/layer_search_filtered.png) |
| ------ | ------ |
| Unfiltered Layer List | Filtered Layer List |
[/REGION]

#### Image Callouts

Often, it will be necessary to create numbered callouts in an image that reference a numbered list in the text. When producing these numbered callouts within the image, the region being called out needs to be outlined with a yellow stroke. Rounded corners are useful to delineate areas of the interface that are adjacent. This should be followed immediately by a numbered list.

The number itself should have the following styling for consistency:


* **Font:** Arial or similar sans serif font
* **Style:** Bold + Italic
* **Color:** Yellow (#fdf242)


![imagecallouts.jpg](imagecallouts.jpg)

1. **Toolbar** - Displays the name of the _Animation Sequence_ currently being edited.
1. **Track List** - Editable list of tracks for creating/editing notifies. See below for instructions on creating and removing tracks as well as creating and working with notifies.
1. **Timeline** - Displays information about, and provides controls for, playback of the preview in the **Viewport** panel.


In this example, you can see how parts of the interface were broken out and numbered, followed immediately by a numbered list.

### Lightboxing

Large image and other content that would be best displayed overlaid on the page should make use of lightboxing. In general, this means enclosing a link within a `lightbox` [region](DocumentationGuidelines/Syntax#Regions). The exact syntax depends on the type of content being lightboxed. See the [Lightboxes](DocumentationGuidelines/Syntax#ImageLightboxing) section on the syntax page for more details.

[refepiclogo]: Logo_Epic-New.jpg "Here's a title"(w:50 h:50 a:left convert:true quality:75 fill:#000000)