Help Pages Guide

Help page requests

To request a new help page or edits to an existing page, please fill out the Help Page Request Form. You can also access this form from the bottom of any help page by clicking “Submit a Help Page Request” which will automatically fill in your contact information and the page URL.

After submitting, you will receive a confirmation email so you can track your request. You will be notified by email when your request is complete.

Making edits to (non-legal) help pages

1. Log in at https://help.fareharbor.com/wp-login.php (see Logging in).

2. From the sidebar, select Help Pages.

   (If you don’t see “Help Pages” in the sidebar, you may need to go to My Sites > FareHarbor > Dashboard.)

3. Use the search box in the upper right to search by title, then click on the page you want to update.

   Tip: If you’re logged into WordPress, you can scroll down to the bottom of any help page and click Edit this post to quickly edit that page.

4. Make your edits and click Update when done.

   Note: Changes on fareharbor.com/ won’t take effect right away unless the WP cache is cleared by an admin. See Adding or updating help pages below for more details.

All client-facing and internal help documentation is managed in WordPress. Log in at https://help.fareharbor.com/wp-login.php and go to Help Pages from the sidebar.

A note about passwords: If you change your password and find that you can no longer log in, message @techwriters. Sometimes WordPress won’t recognize a new password unless the cache is cleared by an admin.

Searching the Help Center

When you start typing in the search bar, suggested pages will automatically appear below based on your query. Clicking on a suggested page will automatically take you there.

Clicking the Search button will take you to a complete list of search results. Results will show any pages whose contents or keywords contain one or more word in your query.

If you are logged into the FareHarbor Admin Dashboard, internal pages are marked with an ‘Internal’ badge in search results. Pages with embedded videos are marked with a video icon, and pages with embedded forms are marked with a form icon.

Searching the WordPress Dashboard

Once logged in to the WordPress Dashboard, you can search the Help Pages section for a specific page by searching for that page’s title.

Hover over the desired page and click “Edit” to make changes to that page.

Note: If you’re having trouble or don’t want to deal with searching 1000+ pages, try using the “Edit this post” shortcut mentioned here.

Here are a few important things to keep in mind when writing help pages.

Writing your content

Use the Content (Markdown) section when adding or updating content. Learn more about using Markdown.

Title and slug

When writing titles, think about what words people will use to search for the information on the page. For client-facing help pages, we try to avoid starting titles with “How to…” and instead state directly what the pages is teaching the user how to do (for example: “Creating a booking”).

The slug is the part of the URL that identifies the help page. By default, the slug will use the same text as the title, but you can edit it if needed. In the example above, the slug has been changed to logging-in (this is because the page is already nested under the FareHarbor app documentation, so it would be redundant to say app/logging-into-the-fareharbor-app).

Page hierarchy

Use the Page Attributes section to manage where the help page is located and how it’s organized within that section.

The first dropdown is a complete list of all published help pages (client-facing pages are listed first, followed by internal pages). Choose the most applicable parent page from the list.

Child pages should be organized in order of relevance. Think about what information people are most likely to search for, and keep those pages at the top.

Keywords

Use the Extra search keywords section to include search terms that don’t already appear in the content of the page. Consider: how would someone search for this topic? What other terminology is used to describe this topic? How might someone spell the topic differently?

For example, you might want to add the keywords “paylink” and “paylinks” for a page about payment links.

Internal vs. external settings

Before publishing, make sure to double-check the View options (located below the Admin Notes section).

• If you are publishing an internal page, be sure to check the boxes “Require user be signed into FareHarbor to view” AND “Require user be a FareHarbor admin user to view”. Additionally, make sure the page is properly nested under an internal parent page.

• If you are publishing an external (client-facing) page but only want it to be visible to people with a FareHarbor login, check the box “Require user be signed into FareHarbor to view”.

Viewing changes

Changes on fareharbor.com/ won’t take effect right away unless the WP cache is cleared by an admin. Usually changes will be reflected within a few minutes.

API Keys

When documenting something that includes API keys or other ‘secret’ credentials, be sure to always use a fake key, and where that’s not possible to remove or censor the actual key as much as possible. Never use a production or a user key in documentation, and if you use a test key try to include as little of it as possible. It’s just good credential hygiene.

Some example fake keys:

abcd1234-0000-1111-abcd-abcdef123456

abcdefghijklmnopqrstuvwxyz

test_key_1234567890

fake-api-key-2020

If you’re documenting a system with a very specific key format (e.g. Stripe) you can use the same format but use invalid, sequential numbers. For Stripe that could be something like sk_test_1000000000 or similar.

Images

To add an image to a help page, select Media from the sidebar menu in WordPress. Upload your image by selecting Add New at the top of the page, then select it from the media library and copy the URL from info panel on the right. Use standard Markdown syntax to insert into the page:

![Image description](Image URL)

(It’s less important to add an image description when working on internal pages, but good to get in the habit of doing so.)

Videos

For client-facing videos, most often they are recorded using RecordIt, and they are then hosted on Vimeo. To insert a video from Vimeo, type the following, replace the < > symbols with brackets [ ], and insert the ID located in the Vimeo URL:

<vimeo id=123456789></vimeo>

Ping @techwriters if you need access to Vimeo or would like to request a video upload.

For internal videos, you may also upload to FareHarbor’s YouTube account and copy the embed code directly into the Content (Markdown) section of the help page. The embed code will look something like this:

<iframe data-ot-ignore width="560" height="315" src="https://www.youtube.com/embed/WMRvY_FNO6k" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>

GIFs

Animated GIFs can be used as a visual aid, but we do not recommend using GIFs longer than a few seconds for the following reasons:

• The reader may have trouble understanding where the recording starts and ends
• The reader cannot pause/resume the recording if they are stuck on a step
• If you’re working on an email campaign, some email clients don’t support GIFs
• Depending on the viewer’s screen, the quality of the image may be degraded

If you need to insert a GIF into a help page, use RecordIt, download the .gif file, upload to WordPress, and use the format below in order to render the gif correctly on the page:

![Image description](https://help.fareharbor.com/wp-content/uploads/sites/278/2020/04/ZEvqpFuj2e.gif)

Gravity Forms refer to the forms managed in WordPress (Gravity Forms is the name of the WordPress plugin). They can be used to gather submissions from clients or employees, and are primarily managed by @techwriters. For more information about forms and how to request updates to them, see the internal Request Forms page.

To add a Gravity Form to a page, use the following syntax but replace the < and > symbols with brackets [ ]:

<form id="000" title="true" description="true"></form>

Make sure to input the actual form ID number, which can be found at the top of the page when editing a form.

Headers

• First level (H1) headers are usually reserved for titles only. Try to avoid using H1 headers in the body of a help page.

• Second level (H2) headers split the page into main sections that can be linked from other pages or support emails. H2 headers can also be collapsed into sections, if needed.

• Third level (H3) headers are also linkable, and generally live underneath second level headers.

• Fourth level (H4) headers live underneath third level headers, and are about the same size as regular bold text.

To link to a specific section on a help page, click the icon to the right of the header and copy the URL in your browser’s address bar.

Links

Any pages that live under fareharbor.com can be linked using their path, i.e. the part of the URL that comes after the domain name.

For example, instead of writing a link like this:

• [Resources](https://help.fareharbor.com/dashboard/resources/)

You can write it like this:

• [Resources](/dashboard/resources/)

…and it will produce the same result. This lets you shorten your Markdown links and reduces clutter.

Some more examples:

• [FH Quickstart](/internal/welcome-to-fh/quickstart/)
• [Changelog](/about/changelog/)
• [Idea Box](/ideas/)

Opening links in new tab

By default, clicking on a link using the Markdown syntax above will open the linked page in the same browser tab, thereby “overwriting” what you are currently viewing. Sometimes you may want to keep that tab open for easy referral. Using HTML, you can set the link to always open in a new tab using the following syntax:

<a href="https://fareharbor.com" target="_blank">FareHarbor home page</a> will open the fareharbor.com automatically in a new tab (user does not have to right-click and select Open in new tab). Note the syntax that enables this behavior is target="_blank".

Bullet Points vs. Numbered Lists

Bullet points are used for summarizing or defining subjects, and should be as succinct as possible. If it can’t fit in 3 lines or less, it probably shouldn’t be a bullet point.

Keep bullet points consistent: If bullet points are complete sentences, they should end with a period. If bullet points are phrases or fragments of sentences, do not end with a period. Try to keep all bullet points in one section the same (i.e. all sentences or all fragments).

Numbered lists are used to outline steps in a process. To keep things clean, it’s generally recommended you format all numbers as 0. and Markdown will automatically render the correct numbers when the page is published.

You can create nested list items by adding a blank line and 4 spaces before the list item. The result will look like this:

• List item

  • Nested list item

Note: If you nest bullet points within a numbered list, the bullets will be formatted as numbers instead.

1. Numbered item

   • Bulleted item (renders as a numbered item)

Callouts, Notes, and Reminders

Callouts are used to highlight important text. Green callouts can indicate a tip or helpful hint, whereas blue or grey callouts might just be an important note or reminder. Orange and red callouts are usually reserved for warnings.

To create a callout, type the following, replace the <> symbols with brackets [], and change the callout color if desired:

<callout color=green>

Text goes here

</callout>

Sections

For particularly long pages with many subtopics, collapsible sections are a nice way to organize the content without overwhelming the reader. Each section will collapse under an H2 header, and expands when the header is clicked on.

To create a collapsed section, type the following in place of your H2 header, and replace the <> symbols with brackets: []

<section heading="HEADER NAME" id="SLUG">

Section text goes here

</section>

The ID is optional, but useful for shortening long header names. For example, the header “How do I set up gift cards?” can be shortened with the ID setup which will be added to the URL when linking to that particular section:

//dashboard/gift-cards/faqs/#setup

Keeping your Markdown clean

When using Markdown, get in the habit of inserting a blank line before and after headers, paragraphs, callouts, and sections. This keeps the content clear and consistent. Inserting a blank line before and after an indented list item or bullet point can also fix unexpected indentation issues.

Insert a space between the hash and header text for better readability. (Example: ### Keeping your Markdown clean.)

• Capitalization: We generally use sentence case for headers and titles in client-facing documentation, although internal documentation is not quite as strict. When in doubt, use sentence case.

• Voice: Although internal pages can be personalized by team, try to keep the voice professional and consistent. Re-read and double check: Would this make FareHarbor look bad if a client accidentally saw it on a screenshare?

• Terminology: Whenever possible, try to use terminology as it appears in the FareHarbor Dashboard. See the glossary for a list of words we use regularly in client-facing documentation, and check out the admin notes for internal terminology.

• API Keys: Never include a complete, legible production API key of any kind in any kind of documentation. Follow the practices here when documenting keys, and if a production key (or any real, usable key) makes it into documentation somehow please let the team responsible for the affiliated system know so it can be rotated.

• We use “Dashboard” as a branded term, so it is always capitalized when talking about FareHarbor. For example, “log into your Dashboard”.

• Since people use FareHarbor on both desktop and mobile devices, try to use generic navigation whenever possible (for example, select instead of click). Be careful when describing the placement of elements in the Dashboard (sidebars might not always be to the left when viewing on mobile, etc.).

• As a rule of thumb, try not to use acronyms or abbreviations, or if you do, be sure to define them. Not everyone may know what these mean.

• MacDown: Free macOS editor for previewing Markdown
• RecordIt: Free tool that captures and creates gifs
• Daring Fireball: More info on Markdown syntax