Name: english-style-guide
Owner: raywenderlich
Description: Style guide for writing in English for tutorials and articles a raywenderlich.com.
Created: 2015-06-05 19:50:19.0
Updated: 2018-05-15 08:39:35.0
Pushed: 2018-05-11 21:26:38.0
Homepage: null
Size: 48
Language: null
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
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. It also covers terms used within Unity tutorials. Finally, we use US English spellings in our publications.
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.
client-side
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
data
The word is plural. Data are, not data is. Except for Lt. Commander Data. He's singular.
delight
Please refrain from using this word when talking about UI animations. You?re a better writer than that.
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
e-commerce
editors Use lowercase; e.g. assistant editor, standard editor, scene editor.
Face ID
frame rate FPS not fps
Git
Unless you're specifically referring to a command using the tool, Git should be a proper noun. When used as a command, make sure to mark it as code: git.
GitHub
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 it's a button name or in a menu command. Otherwise, spell with a lowercase i. When referring to panes in Xcode, capitalize the name of the pane but not “inspector”; e.g., Attributes inspector, File inspector, Size 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.
login, log in
“log in” is the verb. You log in to your WordPress account to write your tutorial. “login” is the adjective (or, if you really must, the noun). “WordPress gives you access to writing tools when it processes your login request.”
long-press
macOS
menu
We use the “?” character for menu separators. To wit: “File ? New ? From Template”. The use of the backslashes ? “File\New\From Template” ? has been deprecated.
K RIGHT-POINTING SMALL TRIANGLE
ode: U+25B8, UTF-8: E2 96 B8
minigame
navigators Capitalize when it's a button name or in a menu command. Otherwise, spell with a lowercase n. When referring to panes in Xcode, capitalize the name of the pane but not “navigator”; e.g., Project navigator, Issue navigator, Test navigator.
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
open-source
OS X Don't use OS X or OSX; it's now macOS.
playground
Podfile
pop-up
Retina and non-Retina
right-click
results sidebar Area to the right-hand side of a playground showing the return value of a statement
SceneKit
server-side
setup, set up, set-up
“Set up” is the verb, where you set up your computer. “Setup” is the noun. The Catterwauls have quite a setup in their video studio.
Take care of those first two forms properly and you?ve covered 95% of cases.
“Set-up” is a common adjectival noun: My mobile carrier has a steep set-up fee. But I wouldn?t slap anyone with a trout for using the above noun form instead: a steep setup fee
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
SpringBoard
SpriteKit
storyboard
superclass
Swift
SwiftNIO Not “Swift NIO”, “Swift-NIO” or “NIO”.
terminal macOS includes a terminal emulator program called Terminal. Generally speaking, use lowercase terminal unless you omit the article:
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.
top shelf No definite consensus on this one from Apple (Top Shelf is used as well); the top area of the tvOS Home Screen.
Touch ID
view controller
Watch app Not watch app or Watch App.
Xcode
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.
code objects
Methods, functions, protocols, classes, structs, variables and so on ? those things that are properly marked inline as code ? are treated as proper nouns. “Add the following to generateLotteryTicket():“, not “Add the following to the generateLotteryTicket() method”.
contractions In general, prefer contractions to the alternative as they enhance the conversational style of our writing.
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
functions see code objects.
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.
methods see code objects.
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.
protocols see code objects.
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.
variables see code objects.
× vs. x
When you?re discussing a 10×10 array, use the typographically correct multiplication symbol ×, as opposed to the letter x or, worse, X.
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
UI
Unity editor
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)
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
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.