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.
- 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
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.
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.
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:
- TextFormField: This widget lets you collect user input.
Long fragment with punctuation:
In this tutorial, you'll learn about:
- Collecting user input.
- Processing user input.
- 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.
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?
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
Kotlin Standard Library (when talking about the official library)
Material Design
Logcat
No "the" before it.
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)
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
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?