by: gregsgourmetPosted on:

Style Guide Sample

Note: This article was exported from Confluence, so the screenshots aren’t as sharp as they once were.

One time, I was in a meeting with a bunch of technical writers and they were passionately debating the use of gerunds in documentation. Meanwhile, I’m sitting there on my laptop trying to figure out what the heck a gerund actually was.

Look, Taylor Swift doesn’t know how to read music. The late and great Ace Frehley didn’t know how to read music. Greg Baldwin doesn’t know what a gerund is. But, gosh darn it, when people read his writing, they enjoy what they see.

Here’s a sample style guide I wrote for creating articles in Salesforce Knowledge. It’s designed primarily for CSRs, CSMs, and other individual contributors on the CS/CX Ops teams. Mind you, I don’t agree with delegating article creation to CSRs and CSMs as that shouldn’t be their job, but that wasn’t up to me.

Salesforce Knowledge Style Guide

Ever hear the saying “style over substance?” Movies, TV shows, books, stat-padding professional athletes on bad teams…there’s a lot of truth to it! However, as you begin authoring articles in Salesforce Knowledge, it’s important for you to write with the mindset of establishing a firm grasp on both style and substance. Perhaps that’s easier said than done but, fortunately, we’re here to help. Think of this guide as a roadmap for developing Knowledge articles; we’ll discuss format, font, menus, image resolution, and general aesthetics. In essence, we’ll bring the style, and you bring the substance.

  • Key Points to Remember
  • What’s in a Title?
  • Article Summary
  • Article Styling
  • Use a Table of Contents/Navigation
  • Things to Keep in Mind/Quick Reference
    (anchor links redacted)

Key Points to Remember

Before we get into it, there are a few essential points to keep in mind when authoring Knowledge articles:

  1. Just get to the point and say what you need to say.
  2. Avoid technical jargon and slang.
  3. Use visual aids to help illustrate your points, i.e. screenshots, videos, and GIFs.

What’s in a Title?

Answer: a lot! One of the quickest ways to find an article in Knowledge is to conduct a search. You could have authored the best gosh-darn Knowledge article ever, but if no one can find it due to the article having an obscure or ineffective title, then all of your written glory goes to waste.

Think of what a customer is looking for while searching for answers: it’s a fact that a poorly-conceived title, such as “This Article Is Useless,” won’t be clicked on by a customer. Use key words and approach as the solution to a problem.

Bad Title: Credentials
Good Title: Getting Started with Credentials in TargetSolutions

Bad Title: Password Reset
Good Title: How to Reset Your Password

Granted, “Password Reset” may illustrate what the article is about, but “How to Reset Your Password” presents the article as an actionable solution to a common problem.

Article Summary

The article summary is a required step for each article, and with good reason. When customers conduct a search, the text that shows up for each article in the results is taken directly from the summary. An effective summary is essentially an introduction for what the article is about, and the problem that the article will be solving. In fact, think of what the first sentence may be for your article, and that could be your summary. Below is an example of an effective summary:

Article Styling

In our world of micro-sized attention spans, having an article that really pops is almost as important as the actual content that’s being presented. Let’s take a look at an example article:

First, take a look at the title and summary: the title is actionable and the summary clearly describes what the article is about. We’re off to a good start.

1. Use of Video: If a picture is worth a thousand words, then a video must be worth a hundred-billion-bajillion. If you have a video for your article, then you should absolutely include it! Some people prefer watching videos; others prefer step-by-step instructions. If you can provide both, go for it.

2. Anchor Links and Navigation: This is particularly important if your article is on the longer side. If your article is short, it may not be necessary. If, however, your article has a little bit of everything, then navigation is a great way to break text up and create some open space. Think of it like a table of contents and determine where each section of an article begins and ends.

3. Use of Headings: Headings are a great way to break up your article and create a little aesthetic organization. They’re easy on the eyes and good for your content. Think of them like chapters in a book. We use Heading 2.

4. Font: The font is configured on the backend, so you don’t need to do anything with it. Just FYI, though, the font we use for articles is Open Sans, size 14.

5. Inner-Article Navigation and Hyperlinks: Linking to other articles is a great way to expand knowledge and keep customers reading. If there’s a relevant article that you can link to, do it! As a note, all hyperlinks in articles should be in bold.

6. Use of Lists: Whether it’s letters, bullets, numbers, or cute animal memes, lists are a great way to break up text and create additional empty space.

7. Use High Resolution Images: Blurry images have no use in civilized societies, so make sure you’re saving your files in high resolution. Microsoft’s Snipping Tool is a free option for taking screenshots and is probably already installed on your computer. Commonly used files are JPEG and PNG. (Greg’s note: the images in the original article are high resolution but did not convert upon export. I understand the hilarious irony of this point).

8. Arrows and Boxes Add a Touch of Class: Use one or the other, or use both! Looking at screenshots shouldn’t be like a game of “Where’s Waldo?” Help everyone out and highlight what you want your readers to see.

9. Leave Them Wanting More!: Include links to related articles at the bottom so customers can continue to read. This keeps each article connected to relevant topics.

10. Include a “Back to Top” Button: If your article runs long, include this button at the bottom (can be configured using anchor links). It’s also not a bad idea to include such a button after each section within your article.

Use a Table of Contents/Navigation

If your article contains multiple headings and topics, then definitely include a table of contents. A simple table of contents, such as the example article above with anchor links, will be sufficient. You can also present your table of contents vertically, such as in this example:

Things to Keep in Mind/Quick Reference

  • The font is configured on the backend, so you don’t need to fiddle with it at all (but, just for fun, the font is Open Sans 14).
  • Heading Size 2
  • Bold all hyperlinks. If it goes somewhere when you click it, make sure it’s bold.
  • Categorization is extremely important, so always be sure to categorize your articles. If you don’t, your article will be placed in ALL SUPPORT CENTERS. Check out this article (link redacted) for more details.
  • Use the Topic section to apply as many keywords as you’d like, and add keywords in the customers’ language! Check out this article (link redacted) for more details.
  • There is no “right” length for an article. Some are very short while others are longer than a Homer poem (but if they get to that length, consider breaking it up into multiple articles).
  • Say what you need to say and be done with it. There are few things more agitating than a support article that rambles on and on about nothing.
  • Empty space is your friend. Massive blocks of text are scary; break up your article and give the content space to breath.