English Style Guide

This is an English style guide that we should follow to stay consistent in how we refer to common things in tutorials.

In general, we follow the AP style guide and the Apple Style Guide. This guide has some tweaks and clarifications on top of those. The guide also covers terms used within Unity tutorials.

iOS Terms and Capitalization

Capitalize and style terms as below.

app Use app instead of application, unless application is more clear or refers to a non-iOS entity.

app delegate

app group

Auto Layout

base 10 ...or base 2 or base 16 or base 8 when “binary”, “hexadecimal” or “octal” won't do. No hyphenation.

Bézier curves

Boolean In honor of George Boole. :]

button Use lowercase, including when instructing the reader to drag one into the scene.

build and run Use lowercase and do not bold.

CocoaPod

Cocos2d Whether and how to capitalize this (cocos2d? Cocos2D?) has been notoriously difficult to pin down, but currently, Cocos2d seems to be the most common form.

Control-click

Control-drag

document outline Apple tends to use the term outline view in its documentation, so that is OK as well; however, use one or the other for consistency.

double-click

drop-down

editors Use lowercase; e.g. assistant editor, standard editor, scene editor.

frame rate FPS not fps

glance Use lowercase, including when instructing the reader to drag one into the scene.

Gmail

group

image view

In-App Purchase When referring to the feature or API. As a singular instance, simply in-app purchase.

information Please, not "info".

inspectors Capitalize when referring to a specific inspector in Xcode; e.g., Attributes Inspector, Identity Inspector.

Interface Builder

interface controller Use lowercase, even when referring a specific, named instance such as the GroceryList interface controller.

iOS 7, iOS 8 Not iOS7 or iOS8.

iPhone 4s, 5s, 5c, 6c Not iPhone 4S, 5S, etc. This is as per Apple.

JavaScriptCore

key-value pair Not "key/value pair".

keyboard keys Spell out and capitalize, whether alone or in multi-press combinations: Shift-Command-Option-X.

You press keys, you don't type or hit them.

label Use lowercase, including when instructing the reader to drag one into the scene.

menu

minigame

Notification Center But a specific instance is usually termed "the user notification center" in lowercase.

Object Library

Objective-C, not Objective C or Obj-C.

OK Don't use okay or Ok.

offscreen

onscreen

OS X Not OSX.

playground

Podfile

pop-up

project navigator

Retina and non-Retina

right-click

results sidebar Area to the right-hand side of a playground showing the return value of a statement

simulator iOS Simulator is a simulator app. Generally speaking, use lowercase simulator unless you omit the article:

Correct: run in the simulator
Correct: run in iOS Simulator (note lack of article)
Incorrect: run in the Simulator

It's OK to both use an article and capitalize Simulator if you are using it as an attributive noun:

Correct: close the Simulator window

size classes

storyboard

superclass

terminal OS X includes a terminal emulator program called Terminal. Generally speaking, use lowercase terminal unless you omit the article:

top shelf No definite consensus on this one from Apple (Top Shelf is used as well); the top area of the tvOS Home Screen.

Correct: close the terminal
Correct: open a terminal window
Correct: use the terminal command
Correct: enter the following command into Terminal (note lack of article)
Correct: open Terminal (note lack of article)
Incorrect: open the Terminal

It's OK to both use an article and capitalize Terminal if you are using it as an attributive noun:

Correct: open a Terminal window
Correct: use the Terminal command
Correct: open the Terminal application

Today As in Today extension, Today view, etc.

view controller

Watch app Not watch app or Watch App.

Xcode

Other Style Guidelines

Apple Use the pronoun it to refer to Apple and any other company or organization; do not use they.

Example: Apple has its own solution...

bolding Use the bold style (<em> in WordPress) for things the reader needs to click, modify, enter into a text field or otherwise notice. This includes file and directory names, but only those that are the action item of a nearby instruction.

When instructing the reader to makes changes, bold each object in the process, with the exception of UI elements.

Example: In the hierarchy, select the SpaceShip and from the inspector, inside the Alien Component, set the IsDead property to false.

Also use the bold style to highlight important concepts that are being introduced for the first time.

For bolding in lists, see lists.

book references References to other books should be italicized:

Example: If you’re new to iOS development, we recommend you start with iOS Apprentice.

chapter references When referring to chapters in the same book, give the chapter number and place the chapter title in quotes:

Example: Chapter 15, “Performance Tips and Tricks”

References to chapters in other books can be written as follows:

Example: Check out the “Doing Cool Stuff” chapter of Ray’s Awesome Book.

coordinates (x, y) not (x,y)

Note that coordinate refers to one of the group (the x-coordinate), while coordinates refers to more than one and usually the entire group (the GPS coordinates of Cupertino).

emoticons These are not punctuation; sentences that end with an emoticon still need appropriate punctuation that should fall before the emoticon rather than after it.

file extensions either XXX or .xxx

game references Italicize the names of published games, like Super Mario Bros. or Angry Birds, but not the names of other software.

headers

Casing in tutorials: Capitalize headers, leaving any article, preposition or coordinating conjunction that is three letters or less lowercase, unless it is the first word in the heading. For example, it is important to capitalize the verb Go but not the word to in Where to Go From Here?

Casing in books: Use sentence casing by capitalizing only the first letter of the first word, except for proper nouns.

Placement: Insert when the subject moves from one point to another; more is usually better than less. Also ensure that if H2 and H3 headers are used they are nested appropriately. For example, there is no point in having a single H2 and then seventeen H3 headings for the rest of the article.

inline code Use the inline code style (<code> in WordPress) for all class, function and method names. Remember to use it for these words: nil
if statement
while loop
if-else
Int
enum
switch statement

lists List items should be followed by colons, not dashes.

If a list includes items, bold them (<em> in WordPress). If the list items are code structures, use the bold style rather than the inline code style.

numbers vs. numerals Spell out whole numbers up to and including nine, as well as larger numbers that can be expressed in one or two words.

Examples: zero, one, nine, six million.

Use numerals for numbers greater than nine; for decimals and percentages; for numbers that express mathematical figures; for addresses, dates, the time of day, and page or chapter numbers; and when a numeral is important for identification purposes.

Examples: 10; 25,000; 30%; divide 15 by 3; Chapter 6; Highway 4; Room 2.

Numbers in series should be consistent.

Example: She went to five countries on four continents in sixteen days OR She went to 5 countries on 4 continents in 16 days.
Example: The final score was 13-1 OR The final score was thirteen to one.

Note: There are a lot of exceptions to these basic rules, so use your best judgment.

quotation marks Punctuation not essential to a quote should be placed outside of the quotes (British style) so as to avoid any possible confusion about whether a punctuation mark is part of a string or any other bit of code.

screen gestures You tap something on a screen, you don't click, touch or press it; the only exception to this is a long press on an object on the phone's screen.

URL Write URLs in lowercase, and leave off the leading www if possible: raywenderlich.com. No special formatting required when the website is part of the main body text.

Unity Terms and Capitalization

Capitalize and style terms as below:

Animator window

animation

Animation view

camera (when talking about the GameObject or when talking about cameras in general)

Camera (when talking about the Camera component)

component

coroutine

Game view

GameObject

gizmo

Hierarchy window

Inspector window

Mecanim

MonoBehaviour

object

prefab

Project window

scene

Scene view

script

sprite

Transform

toolbar

Unity editor

Other Unity Style Guidelines

animated GIFs Use animated GIFs only once for an operation. When repeating the operation, use either a screenshot or refer the reader back to the animated GIF.

project assets All assets in a project should be named using UpperCamelCase.

spoilers Use spoilers to "quiz" readers on repeated operations in the tutorial.

script vs component When talking about the actual .cs file (and the MonoBehaviour class that's inside) call it a script, when you're in the editor and you take that script and attach it to a GameObject, refer to it as a component ("instance" of a script).

camera vs Camera Some common terms like camera, light, collider also have components that are named the same. This can get confusing sometimes. Therefore, when referring to a common GameObject (e.g. the camera) use lowercase, when referring specifically to the attached component use UpperCamelCase.

Vector representations If you describe a Vector2, Vector3 or similar data, use this notation: (X:1, Y:2, Z:3)

Apple Watch Style Guidelines

complications

Digital Crown "the Digital Crown" when referring to the hardware component, but "Digital Crown" when referring to the API.

Dock Also "the Dock"

Home screen Also "the Home screen"

Time Travel

WatchKit

Serial (Oxford) Commas

In general, digital copy looks best when the serial comma is NOT used. This is the general direction followed by several (but not all!) modern style manuals.

An example of the serial comma in use: "Ray wrote three posts, two product reviews, and a scathing exposé on Android."

The preferred practice is to remove the final comma in the list of elements (the one usually before the 'and', 'or' or 'nor' ): "Ray wrote three posts, two product reviews and a scathing exposé on Android."

However, retain the extra comma when necessary to avoid ambiguity: "Ray loves his employees, Tim Cook and Steve Ballmer." Well, we're pretty sure Tim Cook and Steve Ballmer don't work for Ray (just yet), so leave the comma in to be clear: "Ray loves his employees, Tim Cook, and Steve Ballmer."

But beware - the presence of AND following a comma does not imply a serial comma is in use: "Ray continues to throw fits when he sees a serial comma in use, and it's really nervewracking for editors to see their fearless leader in such a despondent state." Here you have two independent clauses that could be written as two separate sentences without losing meaning: "Ray continues to throw fits when he sees a serial comma in use. It's really nervewracking for editors to see their fearless leader in such a despondent state." However, the two share a common idea or thread and you can join them with a comma and a conjunction as I did above.

bryant1410 / english-style-guide Goto Github PK