Quick Tips On Grammar, Punctuation, And Formatting

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.

Grammar and Punctuation

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:

  • Correct: If you go to the store, please pick up markers, paper, and pens.
  • Incorrect: If you go to the store, please pick up markers, paper and pens.

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.

  • Colon Ex: Never forget the golden rule: Treat others the way you want to be treated.
  • Semicolon Ex: We had too many typos; we lost the client.

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.

  • Ex: This is the correct use of my favorite element—favorite grammar element.
  • En Dashes: should be used for ranges in number or dates. It is longer than a hyphen but shorter than an em dash.
  • Ex: 6–7 p.m.

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.

  • Correct: We cut the company's total service time by two-thirds of its prior amount.
  • Incorrect: We cut the company's total service time by ⅔’s of its prior amount.
  • Correct: Please re-enact exactly what happened during the phone call.
  • Incorrect: Do not re-instate him as committee chairperson. (Should be reinstate).

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.

  • Ex Text: “Today, after eating lunch at Jimmy’s, we created a new social media account.”
  • Correct: “Today...we created a new social media account.”
  • Incorrect: Some businesses use social media...some don’t...I’m not sure why.

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.

  • Correct: “To be, or not to be, that is the question.”
  • Incorrect: “To be, or not to be, that is the question”.
  • Correct: What do you prefer, “To be, or not to be”?
  • Incorrect: What do you prefer, “To be, or not to be?”

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.

  • Ex: Shakespeare had a unique outlook on life: “To be, or not to be, that is the question.”
  • Ex: I prefer, “To be” rather than “...not to be.”

Word Choice

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.

  • Active: ServiceTarget releases guides frequently.
  • Passive: Guides are frequently released by ServiceTarget.

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:

  • Incorrect: “I hate passive voice,” says Jacob.
  • Correct: “I hate passive voice,” Jacob says.
  • Also correct: Jacob says, “I hate 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.

  • Ex: “I hate passive voice,” Jacob says. “It makes reading boring and difficult.”
  • Ex: “Those headlights,” she said, “are too bright and make it hard for me to see.”

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.

  • Ex: I do not sound casual right now.
  • Vs. I don’t sound professional right now.  

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.

  • Correct: My company has 597 guides, and 2 of them are unpublished.
  • Incorrect: My company has 597 guides, and two of them are unpublished.

Numbers within a percent should be portrayed as a numeral and numbers in a compound modifier should be spelled out.

  • Ex: My VP of Marketing wrote 12% of our guides.  **% (not percent)
  • Ex: We need to update all of our four-year-old guides.

Decades or centuries should normally be spelled out. If referring to an exact year, use the numeral (Ex: 1987).

  • Correct: The company started up in the fifties.
  • Incorrect: The company started up in the ‘50s.

Use #1 in headlines or any other place that brevity is needed. In the main body text, spell it out.

  • Correct: (Header) We are now #1 in service!
  • Incorrect: (Header) We are now No. 1 in service!
  • Correct: (Body) ServiceTarget has officially been ranked number one in self-service.
  • Incorrect: (Body) ServiceTarget has officially been ranked #1 in self-service.

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.

  • Ex: I have a meeting from 6–7 p.m.
  • Ex: I have a meeting from 11 a.m.–1 p.m.
  • Ex: I have a meeting at seven o’clock.

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.

  • Ex: The meeting will be held at 6 p.m., Tuesday, Aug. 13, 2020, in the conference room.
  • Ex: The company picnic will be in July, 2021.

**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.

Acronyms

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.

  • Ex: Our business is approved by the Better Business Bureau (BBB). The BBB is an organization that...

Formatting Step-by-Step Instructions

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.

  • Ex:  To invite additional users:
  1. Go to the “Users” tab
  2. Click “Add User” and follow the screen instructions

Single-Step Procedures: For a single-step procedure, use the same format, but replace the number with a bullet.

  • Ex: To remove a user:
  • On the User screen, click the “delete” icon on the user you wish to remove.

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.

  • Ex: Select Account > My Orders > Order History.

Keep these tips in mind when creating your content and building a self-help style guide!

Gianna Spitaliere
I love exploring, writing about, and building knowledge on different ways to make businesses and customers more successful all around. I have been with ServiceTarget for less than a year, but have been thrilled to expand my writing into customer self-service.

Want to learn more about what we offer?

Explore the stages of our product tour and the self-service solutions we provide to see how our diverse applications can work for you.

Explore more blog posts!

That's not all! Our blog has tons to offer. Explore more posts below to keep learning!

no code customer experience

No Code Digital Customer Self-Service Platforms - The Benefits

Customer Self-Service

As the world increasingly moves online, businesses are looking for ways to improve their customer experience (CX). Building digital customer experiences does not have to be complicated or time-consuming. With the right tools and approach, you can create amazing customer experiences without a single line of code. In this blog post, we'll discuss different approaches to creating managing, and optimizing the customer experience.

continue reading →
customer self-service portal

Customer Self Service Portals: Benefits and Must-have Features

Customer Self-Service

Customer self-service portals provide an efficient way for customers to access content, perform convenient transactions and resolve common issues on their own, without having to call or email customer support. But not all self-service portals are created equal. In order to be effective, they need to have certain key features. Read on to find out what top features you should be looking for when building your customer portal.

continue reading →
knowledge base content planning

How To Select the Best Knowledge Management System for You

Knowledge Management

There is a lot to consider when evaluating and selecting the best system for your needs. In this blog, we will cover where to search for solutions and what to include on your shopping checklist.

continue reading →
building customer knowledge

Building Customer Knowledge

Knowledge Management

Customer knowledge is rooted in self-service and is fundamental for any successful business. It strengthens product success, which ultimately, creates a successful customer experience as a whole. And this is so crucial today.

continue reading →
customer centric culture

Develop customer-centric vision and culture

Customer Experience

Are you looking for ways to create a customer-centric vision and culture in your business? If so, we're here to help. In this post, we'll outline four steps you can take to create a customer-centric culture in your business. Let's get started!

continue reading →