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!
Explore the stages of our product tour and the self-service solutions we provide to see how our diverse applications can work for you.
That's not all! Our blog has tons to offer. Explore more posts below to keep learning!
Are you looking to improve the efficiency and effectiveness of your customer support processes? One solution to consider is Knowledge-Centered Support (KCS). This blog will provide a step-by-step guide on successfully implementing KCS in your organization. From assessing your current knowledge management practices to training and educating employees, we'll cover all the key steps to ensure a smooth and successful adoption of the methodology. Following these best practices can streamline support processes, reduce the need for repetitive tasks, and improve the overall customer experience. Let's get started!continue reading →
As a business leader, you know that maximizing your team's productivity is essential for success. One way to do this is by implementing a knowledge management (KM) system. KM is the process of creating, sharing, using, and managing the knowledge and information of an organization. By centralizing and organizing information, a KM system can help your team work more efficiently and effectively. In this article, we'll provide eight tips for maximizing your team's productivity with knowledge management.continue reading →
"Are you ready to take your business to the next level? Learn how to build a comprehensive digital transformation roadmap that will help you stay competitive in today's fast-paced digital landscape. Our latest blog article, "5 Steps to Building the Ultimate Digital Transformation Roadmap," covers everything from assessing your current situation to measuring success and staying adaptable. Don't miss out on the insights and strategies you need to drive digital innovation and success. Read now! #DigitalTransformation #Innovation #BusinessGrowthcontinue reading →
As a business leader, you know the importance of digital transformation in today's fast-paced, technology-driven world. But the truth is that many companies struggle with digital transformation and fail to realize its full potential. In this blog, we'll explore the challenges of digital transformation and share tips and best practices for overcoming them. With 84% of companies failing at digital transformation, it's more important than ever to avoid being a statistic. So, if you're looking to successfully navigate the digital landscape and drive innovation in your organization, this blog is for you. Let's get started!continue reading →
If you work in a call center, you know how important it is to handle customer inquiries efficiently and effectively. But with a high volume of calls and a wide range of topics to cover, it can be challenging to quickly find the information you need to assist customers. That's where AI-powered search comes in. This blog will discuss how artificial intelligence can revolutionize call center operations by improving search functionality and streamlining information access. Whether you're a call center professional looking to improve efficiency or a business owner looking to upgrade your customer support, this blog is for you. So, let's get started!continue reading →