kodecocodes/english-style-guide

Style guide for writing in English for tutorials and articles at Kodeco.

English Style Guide

This English Style Guide provides guidance for spelling, capitalization, and usage of common terms. All authors and editors should use this guide so that our articles are consistent site-wide. It's a good idea to skim through this guide before starting any new article, update, or edit as this document evolves continuously.

For questions not answered here, follow the AP style guide and the style guide for your platform, like the Apple Style Guide. For spelling questions, we use Merriam-Webster.

Finally, we use American English spelling and style in our publications. See the American English section below for resources to tell the difference between American and British English.

Table of Contents

• General Terms and Capitalization
• Special Characters
• General Style Guidelines
• Things to Avoid
• iOS Terms and Capitalization
• Android Terms and Capitalization
• Game Technology Terms and Capitalization
• Apple Watch Style Guidelines
• Book Chapter Style Guide

General Terms and Capitalization

app

Use app instead of application, unless application is more clear or isn't referring to a mobile app.

as-is

back end, back-end, backend

"back end" is a noun. You develop the back end. "back-end" functions as a (compound) modifier and is hyphenated before a noun. You are the back-end developer who developed the back end. "backend" is used in the BFF pattern (Backend for Frontend)

You are the back-end developer who used the Backend for Frontend pattern to develop the back end.

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. :]

build and run

Use lowercase and do not bold.

button

The word "button" should be lower-case. The name of the button should be upper-case and bold.

We don't "hit" buttons (or at least, we don't recommend hitting them; what you do in your own office is up to you! :] ). On screens, we tap buttons, on computers, we click them. For example, on iOS, we tap buttons (even on the simulator) and on macOS, we click them. We press keys and key combinations.

Example: "Use the Download Materials button at the top or bottom of the tutorial..."

cancel and related terms

The American spelling of the various forms of cancel is... weird. To keep it straight, here's a list of terms related to "cancel" with the correct number of "l"s to use in each:

• canceled
• canceler
• canceling
• cancellation

checkbox

Not check box. Note that we don't "tick" checkboxes, since that's British English. We either select or check them.

check mark

Not checkmark.

client-side

codebase

Control-click

Control-drag

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).

deselect vs. unselect: If you are talking about removing a check from a checkbox, use "deselect". "Unselect" is incorrect. "Unselected" can be used for an option that hasn't been checked.

• Correct: Scroll down to the newsletter options and deselect "Opt-In".
• Correct: Because the user hasn't completed the form, "Opt-Out" is still unselected.

dialog box: Not "dialogue box".

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-book

e-commerce

editors

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

enter versus return keys

On Windows, enter and return keys are synonymous; on the Mac, they are two different keys.

ePub

file system

frame rate

Use FPS not fps as the abbreviation for "Frames Per Second".

front end, front-end, frontend

"front end" is a noun. You develop the front end. "front-end" functions as a (compound) modifier and is hyphenated before a noun. You are the front-end developer who developed the front end. "frontend" is used in the BFF pattern (Backend for Frontend)

You are the front-end developer who used the Backend for Frontend pattern to develop the front end.

game references

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

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

Gmail

hard-coded

Use hard-coded as an adjective to describe something, but hard code when giving an instruction.

Example: Remember to hard code the hard-coded code into your code.

home page

hot reload and hot restart

Use lowercase and do not bold.

ID not id

information not "info"

internet not Internet.

key-value pair not "key/value pair".

Kodeco

When referring to the company or content we no longer use ".com" as we did on the old site. So it would be "You can find this article on Kodeco", "We at Kodeco can't wait for you to learn with our content" etc.

livestreaming, livestreamed and livestream not live-streaming or live-stream, per the AP Style Guide.

login, log in

"log in" is the verb. You log in to your WordPress account to write your article. "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

object-oriented programming

OK not okay or Ok.

offscreen

onscreen

open-source

playground

pop-up but popover

raywenderlich.com

When referring to the website or our tutorials, refer to it as "raywenderlich.com" in all lower case. Not mixed case (RayWenderlich) or two words (Ray Wenderlich).

real-time

When used as an adjective: "real-time analytics". Real time when used on its own: "We're watching this in real time".

right-click

server-side

This includes the name of the Server-Side Swift pillar as well as all other uses.

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

TODOs

Not todos or to-dos. And certainly not todo's.

webpage

Note that this is a deviation from AP Style.

web service

website

Wi-Fi

This is actually a trademark, though usage doesn't require additional decoration.

Special Characters

apostrophes

WordPress needs straight apostrophes (') not curly or smart apostrophes (’). If your editing tool includes curly apostrophes, please make sure you remove them before adding your article to WordPress. The same applies to curly quotation marks.

menu separators

We use the "▸" character for menu separators. For example: "File ▸ New ▸ From Template". The use of the backslashes — "File\New\From Template" — has been deprecated. However, please continue to use forward slashes as path separators as in "myproject/assets/puppy.jpg".

▸
BLACK RIGHT-POINTING SMALL TRIANGLE
Unicode: U+25B8, UTF-8: E2 96 B8

× vs. x When you’re discussing an array, like a 10×10 array, use the typographically correct multiplication symbol ×, as opposed to the letter x or, worse, X.

General Style Guidelines

above and below

In situations like these: “Here’s how the above function works” and “Add the below function”, "above" and "below" should follow the noun. So it should be: “Here’s how the function above works...” and “Add the function below...”

acronyms

In general, write out the full term followed by the acronym in parentheses the first time the phrase appears if you are going to use the acronym at least three times in the article or if understanding the acronym is important for your article. After the first use, use the acronym.

Example: "Model-View-Viewmodel (MVVM) is a common architecture for app design... In this tutorial, you'll use MVVM to build..."

If an acronym is commonly-used and easily-recognized (i.e., API or HTTP://), don't write out the full term the first time you use it unless doing so is necessary for your article.

Pluralize acronyms by adding a lower-case s to the end, no apostrophe.

Example: "Three commonly-used APIs are..."

American vs. British English

Use American English in your articles. If you aren't sure if you're using the right version, you can refer to this American to British dictionary, check a list of common American vs. British idioms, or paste your text into a British to American converter. You can also read this comprehensive guide to British vs. American language on Wikipedia.

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...

article vs. tutorial

Our internal guideline is to use "article" for our free online text tutorials and "tutorial" for all of our content. Many of our books and videos are also tutorials, after all. However, you can still use the term "tutorial" when you're writing an article. For example, it's fine to write: "In this tutorial, you'll learn all about using animations in your app..."

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 make 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.

Punctuation always goes outside of bold tags. For example, in div notes, you should always use Note: not Note:.

For bolding in lists, see lists. For more information, see Follow Our Formatting Conventions.

book names

When you refer to books, italicize their names.

Example: If you’re new to iOS development and want to learn more, start with iOS Apprentice.

captions

Image captions are treated much like lists: You use punctuation if it's a sentence or longer sentence fragment. You leave it off if it's a single word or short phrase.

The following examples are both correct (punctuation-wise, at least!):

• Example 1: Xcode panel with your code.
• Example 2: Xcode panel

citing sources

When you quote someone either directly or indirectly in your text, introduce the person by their first and last name, followed by their job title or another reason why the reader should be interested in what they have to say on the topic.

• Example 1: Ray Wenderlich, co-founder of raywenderlich.com, said, "When I started as an indie iOS developer, I was so excited and so motivated."
• Example 2: Ray Wenderlich, co-founder of raywenderlich.com, said he was excited and motivated when he started as an indie iOS developer.

If appropriate, link to a bio or other relevant, non-commercial page so the reader can look up more information.

• Good: Ray Wenderlich, co-founder of raywenderlich.com, said, "When I started as an indie iOS developer, I was so excited and so motivated." (Note how the link goes to Ray's bio.)
• Bad: Ray Wenderlich, co-founder of raywenderlich.com, said, "When I started as an indie iOS developer, I was so excited and so motivated." (Note how the link goes to Amazon, a commercial site that doesn't tell the reader more about Ray's experience.)

Upon further mentions in the same text, refer to the subject by last name only.

• Example 3: Wenderlich then went on to say that setting up an accountability system helped to fire up his enthusiasm.

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".

colons

The first letter of a complete sentence following a colon should be capitalized. So both of the following examples are correct:

• There's one thing you should know: thing.
• There's one thing you should know: Never lick a frozen signpost.

Colons should never appear inside bold formatting.

commas

We do not use the serial (Oxford) comma. See the Oxford Comma section below for more details. For all new content and updates kicked off after September 18, 2023, we do use the Oxford comma.

contractions

In general, we prefer contractions, because they make our writing more informal and conversational. Look for phrases like "you will", "it is", "they are", etc. and replace them with "you'll", "it's," "they're", etc.

dashes

We use three kinds of dashes in articles. Please make sure you're using the right one for your needs:

• em dashes (—) join parts of sentences. For example, Learning has never been easier — or more convenient. Read more about em dash usage at grammarly.com.
• hyphens (-) join words. Open-source and front-end design are examples of correct hyphen usage.
• en dashes (–) are slightly shorter than em dashes. They most commonly join spans of time or numbers: i.e., the 1950s–1960s.

data

The word is plural. Data are, not data is. Except for Lt. Commander Data. He's singular.

There are a few cases where data can be considered a singular, collective noun, when you consider the various pieces of data as a set. E.g.: The data is correct. (The data, as a singular collective unit, is correct.) One gigabyte of data is a lot of information to sort through.

emoticons/emojis in tutorials

These don't replace punctuation. Sentences that end with an emoticon still need appropriate punctuation — before the emoticon, not after it. The only emoticon that's appropriate to use in tutorials is: :]

Example: Here's a good example! :]

exclamation marks

Exclamation marks should be used sparingly: no more than once per sentence or paragraph. And not in too many consecutive paragraphs.

file extensions

either XXX or .xxx. For example, JPG or .zip.

first-person language

We generally avoid unnecessary use of first-person language, such as "next, we'll look at some code" or "let's go ahead and add a function". The exception to this rule is when you are adding helpful, first-hand experience. We encourage doing this whenever possible.

For example, in a book about landing a mobile dev job, the author saying, "When I hire new employees, I look for..." is extremely valuable information for the reader. It establishes the author's authority and sets them apart from inexperienced writers. Please do this whenever applicable.

functions — see code objects.

future tense

Avoid phrases that have awkward future tenses like "will be verbing". When you can, use the present tense, which tends to be more exciting.

• Incorrect: In this tutorial, you'll be learning how to...
• Correct: In this tutorial, you'll learn how to...

headers or subheadings

• Casing in articles: Capitalize headers, leaving any article, preposition or coordinating conjunction that is three letters or less lowercase, unless it is the first word in the sentence. 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 title casing in books as well. So Where to Go From Here? or New Features in Swift

• Placement: Insert when the subject moves from one point to another. When in doubt, more subheadings are usually better than fewer. Also, ensure that if H2 and H3 headers are used, they are nested appropriately. For example, there's no point in having a single H2 and then seventeen H3 headings for the rest of the article. For standards on H2, H3 and bolding in headers, see our formatting guide..

• Structure: Whenever possible, headers should start with gerunds: verbs in their -ing form. So Checking Your Code rather than Check Your Code, for example. Also, one subheading shouldn't follow another without any text between them. For example, if you have an <h2> subheading, there should be some introductory text before the next <h3> subheading.

• Objects in code tags: If a heading contains an term that usually uses inline code tags, preserve the term as written but do not use the code tags in the header.

  • Incorrect: <h2>Using spawnEmoji() Without Losing Your Mind</h2>

  • Correct: <h2>Using spawnEmoji() Without Losing Your Mind</h2>

he/she, he or she

Default to "they" instead. If you want to go the distance and correct some of the gender imbalance in this industry, use "she" if you like.

him/her, him or her

Use "them" instead. If you want to go the distance and correct some of the gender imbalance in this industry, use "her" if you like.

his/her, his or her Use "their" instead. If you want to go the distance and correct some of the gender imbalance in this industry, use "her" if you like.

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

in order to...

In almost all cases, "In order to..." can be shortened to "To..." This tightens your prose and saves time for your readers.

introductory clauses

Be sure to add a comma after introductory clauses. Many grammar guides say that the comma is optional for very short introductory clauses, but our style is to always use it.

Examples: "Now, add the following to..." and "To do that, you'll need to..."

it or that

If you use a pronoun like "it" or "that" in place of a noun, make sure it's abundantly clear what you are referring to. Avoid ambiguity.

keyboard keys

Spell meta keys as if you were speaking them out loud. So, for example, most people say "Alt" but not "Esc" or "Ctrl". Therefore, in articles, they should be written as: "Alt", "Escape", and "Control". Similarly, it's "Caps Lock" and "Num Lock" in common parlance, so write those keys that way in articles as well. Any key that makes its own symbol — ".", "a", "." or "-", for example — should just use that symbol.

Capitalize the first letter, whether alone or in multi-press combinations, and bold the command: Shift-Command-Option-X, Control-Alt-F or Shift-Control-,.

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

lists

When you have items introduced in an ordered (<ol>) or unordered (<ul>) list, bold (<em> in WordPress) each item you introduce, then follow it with a colon and the description. Do not use dashes as separators. Those items should be bolded even if they're code structures that would normally use inline code style. The colon should appear outside the bold formatting.

Each list item should end with punctuation if it's a full sentence or a long sentence fragment. If it's a grocery list of short sentence fragments, do not punctuate. All items in a list should either have, or not have, punctuation. When in doubt, opt for punctuation.

Examples:

Full sentence with punctuation. Take note of the bolded code object:

1. TextFormField: This widget lets you collect user input.

Long fragment with punctuation:

In this tutorial, you'll learn about:

1. Collecting user input.
2. Processing user input.
3. Displaying the results.

Short fragment with no punctuation:

raywenderlich.com offers tutorials for the following platforms:

• iOS
• Android
• Flutter
• Server-Side Swift
• Game Technology

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.

pluralization

For acronyms like "API", don't use an apostrophe to make them plural, as per AP style.

Wrong: API’s

Right: APIs

possessive

To make a word ending in "s" possessive, add "'s". For example: "The class's name".

protocols — see code objects.

quotation marks

Periods, commas, dashes, semicolons, question marks and exclamation points go within quotation marks only when they apply to the quoted matter. They go outside quotation marks when they apply to the whole sentence.

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. You don't need to add special formatting (i.e., bold or inline code) when the website is part of the main body text.

variables

see code objects.

Things to Avoid

abbreviations

Don't abbreviate words like "info" for "information" or "congrats" for "congratulations". The abbreviations might not be understood by ESL readers and they look too informal.

delight

Please refrain from using this word when talking about UI animations. You’re a better writer than that.

let's as well as other first-person terms (I, we, etc.)

Avoid these whenever possible, except when you are sharing applicable first-hand experience, as described above. Otherwise, keep the focus on the reader by using you, your, etc.

up

Don't use "up" as an adverb unless it is absolutely necessary. For example, "open up" can almost always be shortened to "open." The same goes for other filler words, like "on" in "click on".

Serial (Oxford) Commas

Note: We've updated our English Style Guide to now include the use of the Oxford comma. If you're working on an ongoing project like a book, video course, or MMLP that started without using the Oxford comma, you may continue without adding it for the duration of that project.

The serial (Oxford) comma is the final comma in a list, usually placed before "and" or "or".

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

We do not use the Oxford comma in our tutorials.

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 nerve-wracking 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 nerve-wracking 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.

paragraph tags

We don't use paragraph tags (<p>) in our tutorials. They can cause problems with rendering, so please make sure to remove any you find.

parentheses

Edit out parentheses in prose whenever possible. Remember, parentheses tell the reader, “I don’t mind if you read over this.” Do you mind if they read over it?

iOS Terms and Capitalization

Capitalize and style terms as below.

app delegate

app group

Auto Layout

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.

Face ID

glance

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

group

image view

In-App Purchase

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

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, SE, 6c, 6s, X, XR, Xs

Not iPhone 4S, 5S, 5C, Se, 6C, 6S, x, Xr, Xs, etc. This is as per Apple.

JavaScript

JavaScriptCore

label

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

MacBook

macOS

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. When using the official term, do not include an article. "Send a notification to Notification Center."

Object Library

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

OS X Don't use OS X or OSX; it's now macOS.

Podfile

Retina and non-Retina

results sidebar

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

SceneKit

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".

Swift standard library not Swift Standard Library

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 / View controller

Use view controller when speaking of an instance in general.

Use View control to reference the four-button unit for changing views of Finder windows. The View control comprises the Icon View button, the List View button, the Column View button and the Cover Flow button.

Watch app

Not watch app or Watch App.

Xcode

Android Terms and Capitalization

Kotlin Standard Library (when talking about the official library)

Material Design

Logcat

No "the" before it.

Game Technology Terms and Capitalization

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.

Animator window

animation

Animation view

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.

component

coroutine

Game view

GameObject

gizmo

the Hierarchy

the Inspector

Material Design

Mecanim

MonoBehaviour

object

prefab

project assets

All assets in a project should be named using UpperCamelCase.

Project window

Rigidbody

runtime

scene

Scene view

script

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).

Shaders

spoilers

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

sprite

Transform

toolbar

UI

Unity editor

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" When referring more generally to a location you choose to store files, "dock" with lowercasing is appropriate.

Home screen

Time Travel

WatchKit

Book Chapter Style Guide

Books use a slightly different style guide than articles do. Here are points to keep in mind when editing books:

Ampersands in Titles

In books, we prefer ampersands to spelling out "and" for both book and chapter titles.

• Correct: Data Structures & Algorithms in Swift
• Incorrect: Data Structures and Algorithms in Swift

Subheadings should still spell out "and".

Chapter References

When referring to chapters in the book you're editing, give the chapter number and place the chapter title in quotes:

Example: Chapter 15, “Performance Tips & Tricks”.

You should not use bold or italic styles for book chapter references.

If you are referring to a chapter in another book, put the chapter name in quotes and the name of the book in italics, like so:

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

emoticons/emojis in books

Emoticons should be used extremely sparingly in books — best is not to use them at all. As with tutorials, only the :] emoticon may be used in books.

Links/URLs

In books, the anchor text should appear in brackets and the URL in parentheses. The anchor text should be short, just highlighting a main keyword or short phrase.

Example: [DartPad](https://dartpad.dev/) is a simple browser-based tool for writing and executing Dart code.

Use bit.ly to shorten long links. You can use bit.ly for any link, but it's a requirement for long ones.

Markdown

While WordPress uses HTML to mark things like bold style, notes, bulleted lists, and so on, our books use Markdown. For example, WordPress marks subheaders using <h2> or <h3> but in Markdown, you'd use ## or ###. You can find the tags you need to use in the Deckle-Flavored Markdown Guide (pw: tutteam). Google can also help you find any tags that aren't on that list.

Paragraphs

Paragraphs can be longer in books than in tutorials. However, be sure that any step-by-step instructions are broken out into lists.

Required Sections

The Key points section is always required in book chapters. The Where to go from here? section is only needed if the author is suggesting the reader check out a significant number of outside resources.

Smart Quotes/Apostrophes

Books use smart quotes and apostrophes (’), whereas articles in Wordpress need straight quotes and apostrophes ('). Although books still use smart (curly) quotes and apostrophes, the conversion will take place after the editing process. Editors should no longer change quotes and apostrophes. This helps keep the diffs clean so authors and other editors can see more important changes in the text. Important Exception: The metadata should include straight quotes and apostrophes only. Editors should fix any curly quotes/apostrophes they see there.

Subheadings

It's especially important to have frequent subheadings in books. You don't want readers flipping through page after page of text with no subheading to mark where they area.

Subheadings in books can go down to the fourth level (####) in books, if necessary. This differs from tutorials, which only go to the third level.

Subheadings that introduce a concept like, "The MVVM Pattern" don't need to be in gerund form.

We use sentence case for subheadings in books, whereas articles use Title Case. That means that only the first letter and proper nouns are capitalized in book subheadings.

We are transitioning from sentence case to title case for subheadings in books. For any new books or updates kicking off after October 1, 2021, please use Title Case. That means that any words with four or more characters, plus any "important" words like nouns and verbs, should be capitalized. Any books that are already being written or updated should continue to use sentence case until their next update.

• Books Kicking Off After Oct. 1, 2021: Where to Go From Here?
• Books That Kicked Off Before Oct. 1, 2021: Where to go from here?

english-style-guide's Issues

Should "document outline" be in title case instead?

Xcode refers to the "document outline" in title case both when you hover over the button in the storyboard and in the "Editor" menu. Should document outline be updated to Document Outline?

Please correct sub title misspelling

Subtitle says: "Style guide for writing in English for tutorials and articles a raywenderlich.com."

Surely that wanty to read: "Style guide for writing in English for tutorials and articles at raywenderlich.com."

Tnx

Path Forward Slash

I propose for all paths, including the tree structures in the project navigator, we follow Apple standards and use a forward slash, like so:

/projects/resources

Control-Click or Control-click or control-click

When spelling out shortcut keys the guide specifies that the modifiers should be capitalized: "Shift-Command-Option-X"

When referring to clicks, the guide specifies that "double-click" and "right-click" should be in lower case.

How should we capitalize control-drag and control-click?

Control-Click or Control-click or control-click
Control-Drag or Control-drag or control-drag

Menu Bar Items

I propose for all menu bar items we follow Apple standards and use >, like so:

File > New > Project

You can see how Apple does this here: https://developer.apple.com/library/content/referencelibrary/GettingStarted/DevelopiOSAppsSwift/Lesson2.html

American and British English spelling differences

Ran into an editor changing recognize to recognise. -ize is more common for Americans.

Perhaps this document can point out our preferred spelling for words with common spelling differences.

Unity Terms & Capitalization

I'm questioning that every term in this section is capitalized. From a few quick searches, the Unity documentation seems to be just as inconsistent as Apple for many of these terms.

We need to be both judicious with our use of capitals and consistent with our decision making—for example, if we use lowercase label and image view, we should probably use lowercase scene and animation view. If we use lowercase project navigator, we should probably use lowercase project browser.

Remember, just because something is capitalized in a menu doesn't mean it should be capitalized in text. Generally everything in a menu is in caps.

Re: GameObject, I would style as either GameObject or game object.

Thoughts?

Misplaced Unity Guidelines

I question whether two of these guidelines belong in the English Style Guide:

• 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. [Note: Changed gif to GIF, as per English Style Guide rule re: file extensions.]
• spoilers Use spoilers to "quiz" readers on repeated operations in the tutorial.

I would argue these are writing guidelines. In fact, there's a section on animated GIFs in the Writing Guide.

I also wonder if these two guidelines can be applied to tutorials generally, not just to Unity tutorials? I think we need to move them somewhere, either to the Writing Guide or to a separate Unity guide.

Book punctuation vs free site content punctuation

Tammy (who cannot be tagged for some reason) requested that we use curly quotes, apostrophes and emdashes with a space around them in printed books.

Should that be part of the style guide? I'm planning to follow the same conventions in the books I'm editing unless somebody tells me otherwise.

@crispy8888 @greystar93 thoughts?

Update Apple Style Guide link

It needs to start with https or it lands on Apple Support (https://support.apple.com/) instead. So, link should be https://help.apple.com/applestyleguide/#/

Pluralization of code objects

I don't think I've seen this covered elsewhere, but the question is straightforward:

Should we refer to multiple UIThing objects as:

UIThings ...or... UIThings?

The former is technically more correct but the latter looks and reads a lot better. Your thoughts, contributors?

Integrating Unity Guidelines

I wonder if these two Unity Guidelines should be folded into the main English Style section(s):

• bolding Often times when writing Unity tutorials, bolding is a multi-step process when making adjustments. Bold each object in the process:
  Example: In the Hierarchy, select the SpaceShip and from the Inspector, and inside the Alien Component, set the IsDead property to false.
• project assets All assets in a project should be named using UpperCamelCase.

I fairly certain the bolding guideline applies to all tutorials; I'm not sure about the project assets one. Thoughts?

Italicization of single letter variables and specifically Big O notation

I assume it is correct to italicize single letter variables that are not specifically used in code:

• There are n items in the array. (correct)
• There are n items in the array. (incorrect)

Does this apply to the O used in Big O notation? Here are some common examples:

• O(1)
• O(n)
• O(n²)
• O(log n)
• O(n log n)

Are the following correct:

• O(1)
• O(n)
• O(_n_²)
• O(log n)
• O(n log n)

_O_(1)
_O_(_n_)
_O_(_n_²)
_O_(log _n_)
_O_(_n_ log _n_)

Editor/Inspector Capitalization

Just wondering about this:
"editors Use lowercase; e.g. assistant editor, standard editor, scene editor."

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

I feel like these two not only contradict one another, but also go against what Apple is doing. Especially when (in the Xcode menus) they are essentially swapped. In Xcode, they read: Assistant Editor and Attributes inspector, respectively. Personally, I think they both should be capitalized. Just my two and a half cents.

Summary edit

Should say "style guide for writing in English for tutorials and articles at raywenderlich.com"

You may thank Tammy for the catch. :]

"top shelf" inserted in the midst of the "Terminal" entry

The title says it all. The entry for "top shelf" separates the guidance for "terminal" from the relevant examples.

em dash usage clarification

When using an em dash (perhaps my favorite piece of punctuation), should we leave a space before and after — as shown in this guide — or should we close the space and just have the dash—as shown in the linked Grammarly blog piece?

Unity suggestions

There are some examples in that list that I'd like to see changed if everyone agrees:

• Prefab > prefab
• Project Browser > Project view
• Unity Editor > Unity editor
• Coroutine > coroutine