kodecocodes/english-style-guide

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

english-style-guide's Issues

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

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

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?

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

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

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?

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

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

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?

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.

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.

Summary edit

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

You may thank Tammy for the catch. :]

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.

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/#/

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?

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

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?

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?