Help:Style Guide

From Mac Guides

Contents 1 Style 1.1 Article titles 1.2 Article formatting 1.3 Internal page links 1.4 External Page Links 1.5 Lists 1.6 Categories 1.7 Templates 2 Language 2.1 Language variation 2.2 First person 2.3 Trademarked terms 2.4 Application names 2.5 Spelling 3 Formatting 3.1 Dates 3.2 Menu items 3.3 Keyboard shortcuts 3.4 File and Folder paths 3.5 Spaces 3.6 Quotations 3.7 Currency 3.8 Units 3.9 Ordering 4 Grammar 5 Links

Style

Article titles

Try to keep your article titles simple, and avoiding using the "The" prefix if possible.

Article formatting

Start an article with a short one or two sentence introduction. This should be followed by a number of headings, created using the syntax: ==Heading text==. Some of the headings should have subheadings, created using the syntax: ===Subheading text===.

Internal page links

Link to existing pages whenever possible, however you should not link to the same article multiple times from one article. For example

Finder and the Dock can both be used to open applications, but the Dock can only be used to open some.

is OK, however

Finder and the Dock can both be used to open applications, but the Dock can only be used to open some.

is discouraged as it links to the Dock article twice.

You should not use any upper case characters in your link text unless it contains a proper noun, for example use

See the article about finding Mac software.

and not

See the article about Finding Mac Software.

If you are considering linking to an article that doesn't yet exist, think about the most likely article name it would have if it were to be created. For example, you could link to a "Calculator" article rather than a "The Calculator Application" article. Also think about how likely it is that an article will be created on the topic, for example you should not create a link to an obscure article like "Finder sidebar" if it doesn't already exist.

The first occurrence of the page title should always be written as a link to that page. For example, in the Mac OS X article, the first occurrence is written as [[Mac OS X]]. This emphasizes the article title within the article.

External Page Links

It is often appropriate to have a links section, often in the form of a "See Also" or "External Links". The only purpose of these sections is to provide links to external websites (but also inter-wiki links and intra-wiki links). External links should take on this form:

  * [<url> <page title>]

Links in a list form should always be preceded with a bullet (*) and display the target page's title, rather than the visually unappealing URL.

Lists

There are different types of lists to use in different situations.

If listing the steps needed to accomplish a task, use a numbered list, for example:

1. Open the Terminal application, located at /Applications/Utilities/Terminal.
2. Type in the command "uptime".
3. Press return.

If listing items without descriptions, or short descriptions for only a few items, use bullet points, for example:

• Finder
• Safari
• Script Editor - used for creating AppleScript scripts
• Mail

If listing items with short descriptions and/or other information, use a table, for example:

Menu Item	Description	Keyboard Shortcut
New Window	Creates a new document window in the frontmost application	Command-N
Open...	Shows an open panel where you can select a file to open	Command-O
Print...	Shows the print panel where you can select printing options and print your document	Command-P

If listing items with descriptions longer than one or two sentences, but no longer than a short paragraph, and limited to descriptions only (ie no additional information such as keyboard shortcuts in the table example), use lists using the "; title : description" format, for example:

Clock 

This menu extra is constantly updated with the current time. Clicking on it displays a menu containing the date, and option to display it as an analog or digital clock, and the ability to open the Date & Time Preferences in System Preferences.

Text Input 

The Text Input menu extra, also known as the International menu extra, allows you to switch between keyboard input modes, such as between American and British or between Qwerty and Dvorak. The input modes displayed in the menu are those selected in the International pane in System Preferences. The menu also provides the useful ability to display the character palette and keyboard viewer in floating windows.

If listing items with long descriptions and (possibly) other information, or if it seems appropriate, use subheadings as in this article. Subheadings appear in tables of contents and can be easily linked to from other pages (using anchors), advantages which other types of lists do not have.

Categories

Always try to assign a category to an article. Assign a suitable category as deep in the category hierarchy as possible, for example the Dictionary article would be assigned to the category "Mac OS X" rather than "Apple Software" (Mac OS X is a subcategory of Apple Software). You can assign an article to multiple categories if appropriate, but only if one is not a subcategory of another.

Templates

There are several templates that should be used in certain circumstances. A list of these is available in the Help:Templates article.

Language

Language variation

You can create an article using either American or International English. Do not edit an article to change it from one type of English to another. However, if an article contains a mixture of both forms, edit it to match the one predominately used in the article.

First person

You should avoid writing in first person; for example, instead of writing "I've found that Finder is not very responsive when dealing with network shares," you could write "The Finder is sometimes criticized for not being very responsive when dealing with network shares."

Trademarked terms

Always use trademarked terms as used by the trademark holder. A list of Apple trademarks is available here. As an example, you should use "Mac OS X" and never "OS X".

Application names

Applications should generally be referred to as either "the [name] application" or "[name]", not "the [name]". For example, the following usage examples are correct:

• Firstly, open the Dictionary application.
• Firstly, open Dictionary.

However the following usage is discouraged:

• Firstly, open the Dictionary.

In some cases, it is acceptable to use "the" without "application", such as when discussing Finder. If you are unsure, follow the previous rules.

Spelling

Spell correctly, and proofread what you write. Use Mac OS X's built in spell check to aid your spelling. Also remember to capitalize, as the Spell Checker will not pick up and find all of your editorial issues.

Formatting

Dates

Dates should be in the format "5 November 2005" or "November 5 2005". Avoid using 5/11/05 or 11/5/05, as these have different meanings depending on the language formats of the reader (or writer) and are therefore ambiguous.

Menu items

If referring to, for example, a "New Window" item in the "File" menu, refer to it as either "File > New Window" (in accordance with Apple guidelines) or "the New Window item in the File menu", but not "File:New Window" or "File->New Window".

Keyboard shortcuts

Keyboard shortcuts should be displayed as "command-control-D" not "command-control-d", "command+control+D", "command control D" or "<command>-<control>-D". Use "command" not "apple", and "option" not "alt".

File and Folder paths

Paths should be in the Unix format, for example "/Applications/Safari". If the file is inside a home folder, use a tilde, for example "~/Library/Preferences/". If the path is to a folder, include a slash at the end, such as "/Applications/" (as opposed to "/Applications").

Spaces

The Wiki software has decreed that one or two spaces it shall be, no more, no less. Three is one to many, and none is one too few. And five spaces is totally out of the question. Thus, as you write the Holy MacGuides Wiki, thou shall follow the Wiki rules of one space, or two spaces, after thine sentences.

Quotations

Use the " character for quotations, not the ' character.

Currency

When listing prices, name the currency. For example, many countries use dollars. Instead of $, use abbreviations like A$, C$, US$ or the appropriate ISO 4217 codes.

Units

Add a space between quantities and units, for example 5 MB, not 5MB. Make sure to correctly capitalize units, for example KB not kb.

Ordering

Items in articles, such as product revisions, should generally be ordered in reverse chronological order, ie with the most recent item at the top of the article and the oldest at the bottom. [1]

Grammar

Make sure to proof read any changes you make to ensure that your spelling and grammar is correct.

Some helpful tips are:

• Remember that "it's" stands for "it is" while the possessive form is "its", unlike other English words.
• Punctuation goes inside of a quotation, "Such as this."

Links

Apple Trademark List
English Grammar Resource

---

Return to Help:Contents