8 min read
Rules we learned about commas and dashes are not very useful if you forget to use them. So we put together these helpful tips on how to maintain grammatical and structural consistency in your self-help content.
As a rule of thumb, following the AP Style Guide is a great place to start when creating any knowledge base content. However, it can become quite intimidating, so we have included some of our best tips and practices to follow in your self-help content to maintain consistency in your grammar, word-choice, and organization.
Headline Punctuation: In titles, don’t use terminal punctuation unless a question mark is required. Commas, em-dashes, or semicolons can be used within the headline, but brevity should be considered first.
Commas: When writing a list, it is helpful to use the serial or “Oxford” comma for clarity. If you have three or more items in a list, put a comma before your conjunction. Here’s an example:
In some instances, this use of the comma may be redundant or unnecessary. As a rule of thumb, always use it. But if a special scenario pops up where it seems the commas are adding confusion rather than clarity, then remove them.
Colons and Semicolons: Use a colon as a pause before introducing related information. Use a semicolon as a break in a sentence conjoining two independent clauses. If the words following the colon are a complete sentence, then capitalize the first letter of the first word. If it is not a complete sentence, do not capitalize.
Em Dashes: for clarity or emphasis. To break up phrases and clauses and/or draw attention to specific information, you can use em dashes. Do not put spaces around them, and use one long dash.
Hyphens: should be used to bring clarity to a compound modifier. They should also be used when spelling out fractions. For the most part, they are not used in compound nouns. Try to avoid adding hyphens to prefixes unless the prefix and root word are using the same letter.
Ellipses: Should only ever be used to display the omission of a word, phrase, line, paragraph, or more from a quoted passage. Do not use to display trains in thought. Leave no space on either side, and use three periods.
Quotation Marks: These should be used when referencing other writers, books, articles, lectures, podcasts, etc. Periods and commas are always placed inside of the closing quotation mark. If your quote ends in a question mark, exclamation point, or other punctuation form (like ellipses) place that before the closing quotation mark.
When introducing a quote with a complete sentence, place a colon before the quotation. If the last word before the quotation is a verb, then use a comma to indicate the person speaking the quote.
Active Voice: Use active voice as much as possible in any writing scenario. Passive voice makes writing more complex and adds unnecessary words. Follow this format: subject, verb, then object.
Said/Says and Quotation Tags: Always tag dialogue with said or says. Getting fancy with something like “...he groaned” distracts and obscures the reader from getting clear and concise content. Use the past tense said when tagging a quote that was pulled from a specific moment in time. Use says when tagging a quote from a present tense source (like an interview). Try to avoid tagging dialogue in passive voice:
When working with larger pieces of quotations (at least one complete sentence), it is useful to break the quotation up and place the tag in the middle of the quote, wherever it may feel natural. This can be especially useful for situations where the reader has spent an entire paragraph reading a quotation so they will not be taken out of it with the clunky tag placed at the end. In order to do this, place _ said/says after the first clause of the quotation. If it is after a complete sentence, place a period after said/says, then continue the quote. If it is not placed after a complete sentence, leave a comma after said/says before continuing the quote.
Use of 1st, 2nd, & 3rd person: First-person should be used at strategic times to humanize your content. Using the personal “I” and “my'' in most scenarios is not necessary, even when referring back to yourself. This is because you are not representing yourself in most content, but the organization you are writing for. Therefore “we” and “our” should be used over “I” in nearly all cases.
Second-person is used most often in emailing and marketing. Directly referring to the audience can be a useful tool in a lot of marketing scenarios. Second person allows the message to come across more direct and clear.
Third-person is more distant, objective, and the least personable. It is used quite often, mostly in more formal reports like reports or corporate forms. This should be used in formal scenarios. But, can be avoided in more relaxed pieces of content where 1st and 2nd person may be favored.
Contractions: Are typically used in more conversational settings. In most cases they should be avoided. In some situations, like a social media post, they can be helpful to purposefully sound more conversational.
Numerals: When writing with numbers, you should spell out numbers under 10. Always use numerals in headlines or headers. When multiple numbers are stated in one sentence they should be displayed following the largest numbers rule to keep consistency.
Numbers within a percent should be portrayed as a numeral and numbers in a compound modifier should be spelled out.
Decades or centuries should normally be spelled out. If referring to an exact year, use the numeral (Ex: 1987).
Use #1 in headlines or any other place that brevity is needed. In the main body text, spell it out.
Times and Dates: Times should be written out in numerals with an en dash connecting a range in time. Morning and afternoon can be abbreviated to a.m. and p.m. in lowercase with periods. If choosing to spell the time out, use o’clock over a.m. and p.m.
When referencing the date, place a comma after the time, day, numerical date, and year. If you are using a specific date of the month, then abbreviate the month (except for March, April, May, June, July). If the month is only listed with the year, then spell it out completely.
**Notice how a comma is still placed after the second period in “p.m.” If you were ending your sentence there, you would not need to add a second period, you would just end on the single one as I did in the beginning of this blurb.
Ampersands: Spell out words like “and” or “plus” instead of “&” and “+.” However, ampersands (&) are acceptable as a shorthand symbol in headers and sub-headers.
Toward vs. Towards: Always use toward without the s at the end. This rule also applies to forward, backward, downward, upward, etc.
Singular and Plural Pronouns: Individual companies, like ServiceTarget, along with nouns like “business,” “brand,” “company,” or “team” are singular and should be referred to with the singular pronouns it or its. If referring to multiple “businesses,” “brands,” “companies,” or “teams,” use the plural pronouns they, them, their, and theirs.
Be cautious when using acronyms. Some acronyms are widely understood and preferred to the spelled-out term, but many are not well known or may be familiar only to a specific group of customers.
Always spell out terms when they appear in the text for the first time and introduce the acronym in the parentheses following the spelled-out term. On subsequent mentions in the same guide, you can use the acronym without spelling it out.
Avoid using an acronym or abbreviation for the first time in a title or heading.
Numbered Lists: Use numbered lists to give step-by-step instructions in sequential order. Parallelism doesn’t have to be followed in this structure, however, content should be written in full sentences. The best practice is to limit the number of steps to seven, and no more than ten.
Multi-Step Procedures: Numbered lists are ideal for instructions that are complex or require multiple steps. Each step should have its own number, and short steps can be combined. Ideally, the number of steps in a guide should be no more than ten.
Single-Step Procedures: For a single-step procedure, use the same format, but replace the number with a bullet.
Simple Instructions: If you need to indicate a path of clicks or a few small steps, right-angle brackets can be helpful. For readability, include a space before and after each right angle bracket. There’s no need to bold these characters.
Keep these tips in mind when creating your content and building a self-help style guide!
.jpg)
.jpg)