Internal FAQ Style Guide

This FAQ Style Guide shows the conventions we use for ClickMagick FAQs so that they have a consistent look-and-feel to them.
Note: There are many FAQs that were written before these formatting guidelines were in place. When you notice something that doesn’t conform to this style guide, take a moment to update it.
Setting Up the FAQ Editor
Before getting into the style guide, you should make sure that the FAQ Editor’s AutoCorrect options are configured so that a lot of basic formatting guidelines happen automatically.
By default, the FAQ Editor converts links into hyperlinks as you type and we don’t want to do that. To turn off this AutoCorrect feature, you need to open the AutoCorrect Options shown here:
You should set the same options for both the AutoFormat As You Type and AutoFormat tabs.
We do want to use curly quotes and use real dashes, so those options should be checked. Just use the exact settings shown in the screenshot above and everything should work just fine.
Using Abbreviations
As a general rule, it’s never a great idea to use abbreviations in business communication unless there’s a strong need to. In particular, always fully spell out “ClickMagick” and never use only “CM” in the FAQs, or in any communication with our users.
The types of abbreviations we want to avoid are known as “lazy” abbreviations, such as using “info” for “information.” One exception to this is the word “stats” which is standard jargon in the click-tracking world.
Acronyms such as “OTO” for “one-time-offer,” etc., should be also avoided unless it would sound awkward saying them each time. If you do need to use acronyms, use the full phrase at least once with a parenthetical reference to the acronym. For example, “if you have a one-time-offer (OTO), you can always...”.
Feel free to use contractions in words. Those are perfectly acceptable.
Spell out Small Numbers
When using numbers to specify “a number of things,” spell out the numbers 0 through 9. For example, write “three URLs” instead of “3 URLs.” This is standard practice in technical writing.
Formatting Tokens, HTML, and JavaScript
All types of computer code should be formatted using the Styles > Computer Code format in the FAQ Editor. You should use this formatting for code even if it is in the middle of a paragraph of text. This eliminates the need to use quotation marks or bold formatting for the code. Here’s how a link using the Computer Code formatting should look:
`http://bestcoolproducts.com/golf`
Showing HTML Tags or the Characters “<” and “>”
If you enter either “<” or “>”, the FAQ lightbox will try to interpret those as part of an HTML tag and won’t necessarily display them properly. (You’ll know this has happened when you view the FAQ and an HTML example—such as a pixel—has “disappeared.”)
So, when you want to actually display “<” or “>” in an FAQ, use “((” instead of “<” and “))” instead of “>”. For example, to display the `<head>` tag, you would actually type `((head))` in the editor.
Line Spacing
For consistency, use two blank lines before any subtitle and before and after graphic images. Also, use two blank lines after any `FAQ`, `VIDEO`, or `LINK` macro (see below).
If the graphic, `FAQ`, `VIDEO`, or `LINK` macros are followed by a subtitle, it usually looks best if you use three blank lines before the subtitle. Use your best judgement ...
NOTE(text), CAUTION(text), and TIP(text)
These three macros create outlined text boxes with icons and background colors related to their meaning and intent. Notes point out details, cautions point out hazards to avoid, and tips point out best practices that should be embraced. (You can see examples of these below.)
These text boxes can contain any content that you want to create for them. If you’re trying to create a box with a lot of content, it may be easier to first create the box with some minimal content, then edit the box after you’ve saved the FAQ once and converted the macro. This prevents problems with embedded parentheses when creating the boxes for the first time.
FAQ(number, Title Text)
This macro creates a nice little page icon followed by the “Title Text” with both the icon and the text linking to FAQ “number”. The macro will automatically create links for both the page icon and the text, and the new FAQ will open in the same window as the current one. Here’s what the generated HTML will look like:

|  | What is the recommended way to set up a custom domain?

LINK(URL, Title Text)
This macro links to other ClickMagick pages or to external pages and opens the link in a new window. This looks just like the “FAQ icon and text” except that you provide the URL to the page rather than an FAQ number.

|  | Click here for Bing’s full set of custom parameters

VIDEO(videoname, Title Text)
The VIDEO macro will create a Play icon with the “Title Text" to the right of it, like this:

|  | How To Set Up A Custom Domain Using a CNAME DNS Record

You can find the `videoname` for any video by going to the Video Tutorials section and hovering over the video that you want to insert into an FAQ. You will see the `videoname` in the link in the lower left corner of your browser window.
IMG(filename) or IMG(URL)
Generates the proper URL for an image uploaded to the ClickMagick site on GitHub. If you need to add a non-ClickMagick image to an FAQ, use the full URL, not just a file name.
For FAQ images, use a maximum width of 600 pixels. This usually means creating the graphic the way you want it, then resizing it down to 600 pixels.
Top Level Menus
When referring to the Links, Funnels, Organic, Rotators, Content, Tools, Help, and Account menus at the top of the screen, use bold font. For example: Go the Help menu and select “1-Hour Support”.
Icon Menus
For the drop-down menus that are represented by icons, we use the spoken name of the menu followed by its graphic symbol. For example, the “Clone” command is in the Edit menu and the Settings menu has the “Split Testing” command. The Report menu can also be useful. Note that the name of the menu is capitalized.
To generate the menu icons, just use the IMG macro with `pencil.png`, `gear.png`, and `page.png`. For example, “Report menu IMG(page.png).” Note that these are `.png` images, not `.jpg`s. This allows the icons to look sharp in the colored backgrounds of `TIP`, `NOTE`, and `CAUTION` boxes.
Menu Choices, Button Labels, etc.
When you name a menu selection in the Settings menu , Edit menu , or Reports menu , put the name in quotes. For example: Go to the Settings menu and select “Split Testing”.
For dialog boxes, use quotes around labels and button names. For example: Enter the URL in the “Page URL” box and click “OK”.
Note: If you’re talking about a menu selection in a top-level menu like the Help menu, you would turn that selection into a link that goes directly to that page. For example: If you need help, just contact us at our 1-Hour Support desk which you can always find in the Help menu.
Other Types of Links
If the various link macros don’t meet your needs, links to other pages in ClickMagick should use the `/user/faqs.cgi` format , leaving off the `clickmagick.com` domain. If the links are included inline in a paragraph, they should be in boldface, and open in a new window (`_blank`) unless they are linking to another FAQ. Inline links will automatically be in “ClickMagick Green.”
Here is an inline example of linking to the Pixel Debugger from within a sentence. Right click on the link from within the FAQ editor, choose Edit Link, and take a look at the settings. Look at the URL and Target settings.
If you are referencing an FAQ or video from within a paragraph, try to rewrite the paragraph so that the FAQ or video reference is on its own line using the `FAQ` or `VIDEO` macros.
Tip: If you’re using the `IMG` macro, all links to images on the ClickMagick site should be generated automatically, but just for the record, all ClickMagick images should have a full URL starting with `//`:
`//cdn.clickmagick.com/…`
This is a “protocol agnostic” style—no `https:` is needed.
Caution: There are two links you can use for FAQs, but only one that you’ll use inside an existing FAQ. The two forms of links are:
`https://www.clickmagick.com/user/faqs.cgi?faq=73`
`https://www.clickmagick.com/user/faqs.cgi?answer=73`
You can find the first version (`faq=`) displayed at the very bottom of any FAQ when it’s showing in a lightbox, and it’s the one that you would give out to people in tickets and so on. The `faq=` version will always open the FAQ search page with the FAQ opened in a lightbox.
The second, `answer=` version simply opens the FAQ in the current window which is why we use this version inside of existing FAQs—so they’ll open in the same lightbox window. The `FAQ` macro automatically generates this second version using its relative, rather than absolute, format: `/user/faqs.cgi?answer=73`
As long as you stick to using the `FAQ` macro, you’ll probably never have to worry about the distinction between the two types of FAQ links.
LI(number)
The `LI` macro generates a series of one-line numeric tables, properly formatted for multiple paragraph text blocks. You would typically use the `LI` macro to list steps in a process: 1, 2, 3, etc. All you have to do is enter the content and everything will already be properly formatted.
$username, $userid, and $ip
Inserts the username, user ID, or user’s IP address of the currently logged in session. Useful for customizing FAQs:
`http://www.clkmg.com/$username/atkinsdiet`
$linkdomain and $rotatordomain
These use an actual custom tracking link or rotator domain in the user’s account—if one exists—otherwise the account URL is used instead. These do not include the `http://` protocol so you have to add it to your examples:
`http://$linkdomain/hoverboard`
That would generate text in the FAQ like one of these two examples, depending upon whether they’ve created a custom tracking domain (`bestcoolproducts.com` in this example):
`http://bestcoolproducts.com/hoverboard
http://www.clkmg.com/username/hoverboard`
Tip: There are many FAQs that could use this extra personalization touch. When you run across these FAQs, update them to give the user that extra warm and fuzzy feeling.
[[TEXT_OPEN row=# cols=]] … [[TEXT_CLOSE]]
These tags open and close a multi-line `<textarea>` … `</textarea>` block. They are rarely used, but when you need them, here’s how to do it:
[[TEXT_OPEN rows=5 cols=30]]
Enter default text here...
[[TEXT_CLOSE]]
Linking to the 1-Hour Support desk
There are two links you can use to reach 1-Hour Support depending upon what you’re explaining in the FAQ.
In almost all cases, you do NOT want the link you would find in Help menu. That link forces users to enter an FAQ search, which they just did if they’re currently reading an FAQ with a 1-Hour Support link in it …
In this scenario, we want the 1-Hour Support link to bypass the FAQ page. To do that, use this link:
`/user/action/account/help.cgi?action=helpdesk`
In the rare case when you want the user to go to the actual page they’d reach by choosing “1-Hour Support” in the Help menu, you would use this link:
`/user/action/account/help.cgi`
In either case, be sure to open the link in a new window.
Tip: To make things even easier, the FAQ editor has a “SUPPORT” macro that will create the link for you. Just write something like, “Please contact our SUPPORT desk if you need additional help.” The word “SUPPORT” will be replaced and the sentence will read “Please contact our 1-Hour Support desk if you need additional help.”
Linking to Specific Categories on the User Profile Page
To set up a link to a specific category on the “User Profile” page, use these links, opening in a new window:
`/user/profile.cgi?cat=auditing
/user/profile.cgi?cat=traffic
/user/profile.cgi?cat=monitoring
/user/profile.cgi?cat=publicstats
/user/profile.cgi?cat=misc`
Adding $ signs in FAQs
The “$” sign is treated specially in FAQs so that things like `$username` and `$userid` will be substituted with other values. If you use a “$” sign without taking any precautions, it will probably just “disappear” when the FAQ is displayed.
To make sure that “$” signs show up, simply put a “\” in front of them. For example, to write “$20”, you would actually enter “\$20”.
Consistent Terminology
In some cases precise terminology is important.

User vs. Visitor | In the FAQs, a “user” is a ClickMagick customer, whereas a “visitor” is someone who clicks on a tracking or rotator link. It’s easy to get these two terms mixed up when writing an FAQ, so if you run across an FAQ that needs updating, feel free to do so!
Cloaking vs. Masking | ClickMagick uses the term “cloaking” rather than “masking” so always use the word “cloaking” in the FAQs. When adding keywords, be sure to include “mask” in any FAQs related to cloaking.
Drop-down vs. Pop-down | Most people would say these terms are identical, but technically “pop-down” menus only stay down while you’re holding the mouse button down. ClickMagick only uses drop-down menus, which stay down even if you let up on the mouse button. For consistency, if nothing else, let’s stick with “drop-down” in the FAQs.

Common Misspellings that Show Up in FAQs
Words and phrases like “setup” and “set up” need to be used carefully. “Setup” as one word is a noun, whereas “set up” as two words is the verb form. So, you would say,
The new setup was set up the other day.
That’s correct. Lot’s of “up” words work this way. “Setup” and “set up”, for example… You find the same issue with “in” words and phrases such as “login” and “log in”, “signin” and “sign in”, etc.
If you have a situation where you’re unsure which form to use, put the word or phrase in the past tense and see if it makes sense. For example: “I setupped the computer the other day” doesn’t make any sense, so you know “set up” should be two words: “I set up the computer the other day”. (“Set” is the past tense of “set”...)
A more obvious example uses “login”: You wouldn’t say “I loginned the other day”, but you would say “I logged in the other day.” You can see the difference here:
I logged in by entering my login information.
In the first use, you’re forced to use two words, whereas the second use, you’re not, so in present tense, you would write:
I log in by entering my login information.
Make sense?
Creating Keywords for Awesome Search Results
You should add keywords to every FAQ that you create. This topic is so important that we have a separate FAQ just on this topic:

|  | Creating FAQ Keywords for Awesome Search Results

Checking FAQs for Correctness
Make it a habit to use the FAQ Check All tool to scan all of the FAQs looking for bad links and other problems that sneak in and need to be corrected. The tool can take up to a minute to run, so be patient.