FareHarbor Style Guide

About this guide

This Style Guide is to be used when writing help pages or other FareHarbor-specific documentation in order to ensure clarity and consistency in style, formatting, usage and structure.

These are guidelines, and should therefore be adhered to when writing content for the FareHarbor Help Center. If an occasion arises where you are unsure about how to phrase or format something, you can always ask a technical writer, or, alternatively, refer to the Google developer documentation style guide for more information or clarification.

Abbreviations

Acronyms

Capitalization

Colons

Commas

Contractions

Dashes and hyphens

Dates

Examples

Footnotes

Gender

Jargon (slang)

Keyboard references

Language and locale

Numbers

Notices (Warning, Note, Important, etc.)

Point of view

Procedures

Pronouns

Quotations

Slashes

Steps

Tables

Time and time zones

Titles

UI elements

Verbs

Miscellaneous expressions

Internal-only content. Don't copy and paste to anyone.

About this guide

This Style Guide is to be used when writing help pages or other FareHarbor-specific documentation in order to ensure clarity and consistency in style, formatting, usage and structure.

These are guidelines, and should therefore be adhered to when writing content for the FareHarbor Help Center. If an occasion arises where you are unsure about how to phrase or format something, you can always ask a technical writer, or, alternatively, refer to the Google developer documentation style guide for more information or clarification.

Abbreviations

Standard abbreviations can be used in places where no further clarification is necessary.

For example:

In a Location field you can use Ave., St., Rd., Hwy, etc. In all other instances you should write out words that are either FareHarbor-specific or not generally understood.

Nouns such as demo, app, and sync are acceptable abbreviations in most instances. Their verb equivalents should be written out.

For example: “I would like to demonstrate this function for you”. See this page in the Google Developer documentation style guide for more information.

The following abbreviations should not be used, but written out as indicated:

• Use in other words (and not i.e.)
• Always write out as for example, do not use e.g. and ex.
• etc. always ends with a period.
• Write out as also known as, not aka.

Acronyms

The first instance of an acronym that is not widely understood must always be spelled out, followed by the acronym in quotes enclosed in parentheses.

For example:

✅ Google Things to do (TTD). From that point forward, Google TTD can be used.

Some less common acronyms such as EMV and FHDN do not have to be written out.

Acronyms are capitalized.

Capitalization

This large section provides rules for capitalization.

Bulleted lists

All items in a bulleted list should begin with a capital letter, except if they are a continuation of the previous paragraph.

For example:

• Creating an item
• Updating item descriptions
• Updating an item’s online booking settings
• Adding and updating item photos

FareHarbor-specific terms

• Dashboard is a branded term and should always be capitalized.
• Lightframe is a branded term and should always be capitalized.
• FareHarbor Support and FareHarbor Help Center should be capitalized.
• Unless being used as part of a navigational element, all other FareHarbor terminology and features (invoices, booking flows, custom fields, customer types, outside users, price sheets, etc.) should be lowercase.

Similarly, these FareHarbor-related product names are capitalized in the following way:

• Booking.com
• FareHarbor Compass
• FareHarbor Connect
• FareHarbor Distribution Network (FHDN)
• FareHarbor iOS app
• FareHarbor Android app
• FareHarbor Sites

Commands

Capitalize at the beginning of a sentence, but not within a sentence or step, unless they are capitalized in the app.

For example:

✅ Enter your username and password, then click Save.
❌ Make sure to Save your changes.

Currency

The first two letters in three-letter currency abbreviations are generally capitalized, followed by the symbol for the currency.

For example: €, UK£, US$, CA$.

You can also use the full currency codes without the symbol, such as: EUR, GBP, CAD, USD.

Currencies when written out are not capitalized.

For example, The activity costs 1,400 euros (or dollars, pounds, pesos, etc.).

Note: For the euro (€), anything more than 1 requires the plural, euros.

Environment variables (OS versions)

OS versions are preceded by the full word version, lower-case.

For example:

✅ You must be using version 10.1 of the FareHarbor app in order to use this feature.
❌ You must be using V10.1 of the FareHarbor app in order to use this feature.

Filenames

Filenames should always be in all lower-case letters.

For example:

✅ ../myfile.jpg, even if the original uses a capital.
❌ ../MyFile.JPEG

Headings

If using H1, H2, H3, H4 or H5 (Markdown #, ##, ###, ####, #####), only the first word of the heading should be capitalized, unless there is the name of a third-party product mentioned in the heading. For example: “Scanning QR codes using the Koolertron handheld scanner”.

In some instances, a product name may begin with a lowercase letter, such as iPhone. If this is the first word in a header, keep the same official capitalization.

Permissions

The name of the permission group is capitalized by default, but group is lower-case.

For example:

“You must have Director or Administrator permissions to make changes to this setting”.

Third-party Product names

Always refer to the company’s website for confirmation of correct spelling and capitalization.

Third-party product (software) names

Follow the capitalization as used by the manufacturer or developer of the software.

For example:

• Adyen
• Airtable
• Apple Pay
• Bluetooth (always capitalized)
• Boca (tickets, printer)
• Close (not Close.io)
• Expedia.com, Expedia Local Expert
• Google
• Google Pay
• Google Analytics (not “GA”)
• Google Things to do
• JavaScript
• PayPal
• PicThrive
• Smartwaiver
• Tripadvisor (not “TA”)
• Tripadvisor Review Express
• Wherewolf
• Zendesk

Note that trademarks (™), registered (®), and copyright (©) symbols are not used in our documentation.

Colons

Colons are used mainly to introduce a procedure.

For example:

To send an email to your customers:

1. Step 1
2. Step 2, etc.

Colons can also be used to indicate that an image (or video) follows that step (or sentence). For example: The availability updater shows how many availabilities will be updated, as in this example: (screenshot)

Commas

Use the Oxford comma.

✅ This event occurs on Monday, Tuesday, and Wednesday.
❌ This event occurs on Monday, Tuesday and Wednesday.

Contractions

✅ Certain contractions can be used in help pages, such as:

• You’re
• It’s (meaning “it is”, not the possessive of “it”, which is “its”)
• We’re (example: “We’re here to help!”)
• Can’t (use “cannot” if written out)
• Won’t (use “will not” if preferred)
• You’ll (use “you will” if preferred )
• They’ll (use “they will”)
• We’d (use “we would” or “we could”)

❌ Avoid using:

• There’ll (use “there will”)
• There’d (use “there would”)

Use your judgment when deciding whether to use a contraction, based on the audience and type of document you are writing. In most cases, contractions can provide a friendlier, more informal tone, especially in client-facing help pages.

Dashes and hyphens

Dashes are only used to hyphenate words, and only require one per phrase.

For example:

✅ Click the button in the top-right corner of the page
❌ Click the button in the top right corner (or top-right-corner)

✅ Right-click on the link to open it in a new tab. (Note: You do not double-click on a link).
✅ Double-click on the icon to open the program.

✅ Wi-Fi
❌ Wifi or WiFi.

Dates

Spell out the date in full words using “MMMM dd, yyyy” format.

✅ January 23, 2000
❌ 23 January 2000 or Jan. 23, 2000
❌ DD/MM/YYYY or MM/DD/YYYY (23/01/2000 or 01/23/2000) to avoid confusion.

Examples

Examples should be preceded by the word “example” or “for example”, and never “e.g.” or “ex.”.

If a screenshot is being used as an example, use “…as shown in the following example:” before adding the screenshot.

Footnotes

Footnotes are generally not used in help pages, however in rare cases they can be added. To learn more about using footnotes in Markdown, you can refer to a third-party resource such as this page.

Gender and Pronouns

Writing should be gender-neutral. We do not use “he/his/him”, “she/hers/her”, but “they/their/they’re”. This is particularly important when referring to customers.

✅ Ask the customer to enter their credit card number in the payment field.
❌ Ask the customer to enter his credit card number in the payment field.

For external-facing help pages, never use “the client”, always use “you”. For internal-facing help pages (and Admin Notes), “the client” is preferred over “you”, unless referring to a FareHarbor admin.

When referring to an end customer, always “they” and not his/her or any form thereof. The possessive pronoun for an end customer is always “their” or “theirs”.

Jargon (slang)

The use of jargon or slang should be avoided, as these words can be region-specific, and do not translate well into other languages or cultures.

✅ Please reach out to [FareHarbor Support] for additional assistance. ❌ Feel free to *ping your Account Manager for more information.

Keyboard references

Use the following formats for specifying a key combination for shortcuts when navigating through the Dashboard.

• The action is always Press, not click the key.
• Control vs. Ctrl: Spell out the names of the keys.

For example:

Press Control+C to copy to your clipboard (or command+C on a Mac).

• Spell out names of characters that could be confusing.

For example:

Press Shift+comma to access the Advanced Settings.

Key names or combinations should always be shown as code.

For example:

Press Enter.

In most instances, it is preferable to use Windows keyboard key names (and Mac equivalents in parentheses, if necessary). Refer to this article for Windows keyboard names and their Mac equivalents.

Language and locale

All writing must use American (US) English (en-US) spelling. We do not use any British or other international spelling.

For example, we use:

• program, not programme
• color, not colour
• organization, not organisation
• select, not tick
• FareHarbor, not FareHarbour
• analyze, not analyse

See also Jargon.

Numbers

Words or numerals

Any numbers ten and under are written out. Numerals are used from 11 upwards.

For example:

There are ten customers on that date, and 30 for the following day.

Ordinal numbers

Spelled out where appropriate, e.g. fourth, not 4th for ordinals up to tenth. For 11 and higher, write 11th, 12th, 13th, etc.

Ranges of numbers

Shown using a hyphen, e.g. Read pages 1-4 for more information.

Time (duration in hours and minutes)

Follow the same rules as for Words or numerals.

For example:

The activity will last four hours in the first week, and 11 hours during the second week.

Notices (Warning, Note, Important, etc.)

In most instances, make sure that the notice phrase is in bold and followed by a colon.

For example:

✅ Note: You may have to restart your computer or clear your browser cache.
❌ Note that you have to restart your computer or clear your browser cache.

✅ Important: You must complete the following steps before proceeding!
✅ Warning: If you do not click Save, your changes will not be saved.

It is also acceptable to use an emoji or icon to call out something that is Important, a Tip, or a Warning.

Point of view

• You is used when addressing the person reading the help page. “The user” is not used in client-facing pages.
• For client-facing content, do not use we, us or our when referring to FareHarbor, always use FareHarbor.

Procedures

Procedures should always be introduced with the word “To” followed by what the procedure will accomplish, and end with a colon (:). Note the introduction should be in bold letters.

For example:

To send an email to a customer:

Writing procedural steps

• Always use a numbered list.
• When possible, each step should begin with a verb, for easy identification of the actions the user will take.

For example:

1. Navigate to Settings > Users & Permissions.
2. Click …
3. Select …
4. Enter … in the dialog box.
5. Click Save.

• All steps must end in a period.

• If an image is included between steps, you can use a colon (:) instead of a period at the end of the step.

For example:

1. Click the green button as shown below: [*insert screenshot here]

It may not make sense to begin a step with a verb, in which case it is acceptable to include the action verb later in the step.

For example, both of the following wordings are correct:

✅ At the top of the page, click Bookings to access the booking calendar.
✅ Click Bookings at the top of the page to access the booking calendar.

Quotations

Quotations are rarely used in help pages, however in the event it is appropriate, use a commma after the quote (place outside the closing quotation mark).

Note: When copying text from Google Docs and pasting into WordPress Markdown, you may need to update any quotation marks to make sure they are shown as straight quotes, not curly quotes.

Slashes

The use of slashes should be avoided where it is possible to substitute the slash with a preposition or conjunction

For example:

✅ The following are the hardware and software requirements for using FareHarbor.
❌ The following are the hardware/software requirements for using FareHarbor.

Exception: The use of and/or is acceptable.

Steps

Ordered steps constitute a procedure. See Procedure for the rules.

Tables

Tables are useful when you have a multi-column block of information that would be best shown in rows. The following are two examples of when tables would be most useful:

• For displaying information for easy comparison between items.

A good example: Overview and comparison of card readers.

• For listing countries and access phone numbers, currencies, account manager, etc.

Note: There are some third-party tools to make creating tables in Markdown easier. One of them, Markdown Table Generator, generates the Markdown that you can copy and paste into your help page.

In addition, there may be some instances where embedding an Airtable base or Google Sheet would be preferable. This is particularly true when frequent changes are made and need to be reflected immediately, without having to log a help page request.

Time and time zones

Use AM and PM (12-hour clock) and not the 24-hour clock. AM or PM should be capitalized and preceded by a space.

For example:

✅ The availability start time is 1:15 PM”.
❌ The availability start time is 13:15.

Range of years

For a range of years, do not use an apostrophe.

✅ 1980s
❌ 1980’s

Time zones

Write out the full name, followed by the three-letter abbreviation in parentheses

For example:

“The activity will take place at 3:00 PM Pacific Standard Time (PST).”

For a full list of universally recognized time zones, refer to this page.

Titles

• Help pages
  • Always use sentence case.

For example:

Using the availability updater or Creating a new booking for an existing contact. * Screens and menus * Match the name exactly as shown in the UI * Dialog boxes * Match the name of the dialog box exactly as shown in the UI. * Table and column heading titles: Always shown in bold and in title case.

When writing in title case, capitalize the first letter of each major word except for short articles and prepositions. If you’re unsure what to capitalize, check capitalizemytitle.com.

UI elements

UI elements should be capitalized to match their name in the UI.

• Checkbox: singular, one word (not hyphenated).
• Dialog box: Always use this phrase, never “dialog” by itself. Note: the correct spelling is dialog, not dialogue.
• Dropdown: Interchangeable with list or menu. Examples: dropdown list, dropdown menu.
• Menu bars: Use menu, or navigation bar or toolbar if shown at the top of a window.
• Menus and menu options: Always shown in bold.
• Radio buttons: Use “Select” and not “click”.
• Toolbars and icons: Toolbar used when there is a set of icons or buttons from which the user will choose an option.
• Keyboard keys and shortcuts.

Verbs

Verbs must match the following rules.

Collective nouns and verbs

• Data is a singular collective noun, so it uses the singular verb.

For example:

“The data is (was) useful for troubleshooting”.

Singular and plural versions of nouns in the same clause take the singular verb.

For example:

“The number of availabilities is limited to three per day.” because the subject “number” is singular.

Tense

Present tense is used, unless something has definitely occurred in the past.

For example:

✅ When you make a booking, the number of available places for that availability is reduced.
❌ When you make a booking, the number of available places for that availability will be reduced.

Voice

Use active voice when writing about what a person does.

For example:

✅ Click the Send text or email button to contact your customer.
❌ The customer is sent the Send text or email button.

Passive voice should be avoided, because the subject of who is performing the action is not always easy to determine.

Miscellaneous expressions

Above and below

✅ See the paragraph [above][below] for more information.
✅ Follow the steps below to send a reminder email.
❌ See the [above][below] paragraph for more information.

Drag and drop

This expression is not hyphenated.

For example:

“To reorder the list of bank accounts in your Dashboard, drag and drop the account to the desired location”. However, it is hyphenated if used as an adjective, such as “You can use the drag-and-drop feature to move items on the page”.

(Note: The past tense of drag and drop is dragged and dropped.)

Login vs. log in (also: logout vs. log out)

Login is a noun or adjective, depending on context.

For example:

“Enter your login name and password” or “My login name is John Traveler”.

Log in is a verb.

For example:

Log in to the website using your FareHarbor username and password.

Up to date

Not hyphenated unless used as an adjective.

✅ Make sure your computer is up to date.
❌ Make sure your computer is up-to-date.
✅ Make sure you are using the most up-to-date version of the FareHarbor iOS app.