Style guide

The Ellipsis style guide is our cross-client house guide. This should always be accompanied with client-specific style, which you can get from content requirements. Also relevant is the editorial checklist and the A to Z.

Acronyms

  • The first time you use an acronym that may be unfamiliar to a reader, spell it out in full, followed by the acronym in brackets. Thereafter, you can use the acronym alone.
  • Example: WordPress is the most commonly used Content Management System (CMS).
  • However, if this is a product name, opt to write it out in full wherever possible and only use the acronym if it helps reduce repetition.
  • Example: Studio Wombat’s Advanced Product Fields (APF) is a great all-rounder plugin. In this article, we’ll look at how to use APF to add radio buttons to your WooCommerce store.

Background and assumed knowledge

  • Assume a level of knowledge in line with the complexity of the keyword and title.
    • A beginner guide needs to explain everything whilst any indication the searcher is solution-aware, and we can start assuming they have some context.
    • There’s a balance required here. Someone searching for how to buy a car doesn’t need the history of cars explained, but they might need some context about the specific model they’re looking at.
    • As long as the searcher plausibly already knows the background, we’re fine to skip it.

Bullet points and numbered lists

  • Always begin a bullet point with a capital letter and end with a full stop (even if it comes after a colon) – apart from when you are writing a short, itemised list where each bullet point is no longer than 2-3 words. In this instance, you don’t need to use full stops or punctuation.
  • For lists that are part of tutorials with a lot of text for each point, and/or the points are interspersed with images, use regular paragraphs with a number at the start rather than formatting them as a list.
  • Consider whether a bullet point or numbered list is most appropriate. If your list is ordered, for example a top 5 or a step-by-step, then numbers make sense. For unordered lists, bullet points are better.

Brackets

  • You can use brackets in place of a pair of dashes or commas when you want to add a short definition, explanation, or extra information.
  • Try to keep the word count to a minimum in brackets, as you don’t want the sentence to be made up of more words in brackets than outside of them.

Brands

  • Brands not to mention:
    • YITH – Someone pretending to be YITH has been filing DMCA requests to get content that mentions YITH removed from SERPs. Avoid mentioning and linking them if possible.

Capitalisation

  • Entities, product names, and brand names should always be capitalised.
  • Always check how brand names are spelled, and write them out as they do on the brand website.
  • Example: Airbnb, not AirBnB. Facebook, not FaceBook.
  • When writing code functions, always use lowercase and format the wording as code.
  • Example: wp_woocommerce_session not Wp_woocommerce_session

Colons

  • Use colons sparingly, in order to keep sentences shorter and more accessible.
  • As a general rule, never capitalise a word after a colon, unless it is a proper noun or an acronym. The exception to this rule is when it isn’t placed within a sentence and is used in list/bullet point format OR in a title/heading.

Citations and source quality

  • When citing a source, always link the relevant part of the claim, particularly when referring to a number or statistic.
  • Sources should be authoritative. You want to look for quality, reputable sources like academic publications where possible.
  • Always link primary sources, and never link secondary sources. The primary source is the publication that is publishing the research/claim. You should be suspicious of statistic roundup posts, as these are often link-bait with little care for accuracy. Always fine the original source, even if this is buried.
    • In this statistic post, for example, the stats are presented as though they’re primary research as there’s no source next to them. But if you check the bottom of the article, you’ll find all the sources dumped together. We need to find and then check the accuracy of the stat we’re using.
  • Example:
    • “In the last few years, the effectiveness of traditional one-size-fits-all teaching methods has been questioned, especially as college dropout rates increase.”
    • The claim that college dropout rates are increasing needs to be cited.

Dashes and hyphens

  • Only use the n-dash (–) and hyphens ( – ). Don’t ever use the m-dash (—).
  • You can use the n-dash in place of round brackets or commas, separated by spaces.

Ellipsis

  • Use ellipsis very sparingly. It should only really be used when you are shortening a quotation. Don’t surround it with spaces.

First-person

  • Unless a client’s specific style guide says otherwise, don’t write in the first person, but don’t write too explicitly in the third person, either. Be neutral in writing in reference to the client’s product, without using “they” or “we” – use the client’s name instead.
  • Example: “[client] is a solution that XYZ” – not – “Here at [client], we do XYZ”.

Formatting

  • If you’re using bullet points or a numbered list, use the actual formatting for those.
  • The only exception is if you’re writing a tutorial with numbered steps AND a lot of text + images on each number. For these, just use paragraphs with numbers at the start.

Headings

  • Don’t use “Conclusion” as a final heading. Be more descriptive!
  • Heading casing:
    • We use sentence case unless the client has specific other requirements.
      • This is an example of sentence case
      • This Is An Example Of Title Case, Which We Don’t Generally Use
    • If the client does require us to use title case, make sure you’re using it correctly! Unless the client specifies otherwise, we use Chicago title case, titlecaseconverter.com will do it for you.
  • Use the heading formatting in Google Docs/WordPress, rather than just making the text bigger.
  • The next paragraph should start immediately after the heading, with no additional line breaks.
  • Question headings
    • We usually want at least 1 heading in the content to match a “people also ask” question.
      • For example, for the keyword “WordPress plugin development cost”, we can target the heading “What are custom WordPress plugins?”. This heading has a featured snippet, and we can increase the value of the content by ranking for this snippet.
        • In order to have a chance for ranking, we need to do best practices for getting a snippet like this.

Heading structure

  • Use a logical heading structure:
    • Heading 2 (H2)s for main section titles.
    • Heading 3 (H3)s for sub-sections of main sections.
    • You should rarely use H4s. We don’t use them in the vast majority of content. Only use them if Strategy have specifically flagged.

Images

ALT text

Copying images from Google Docs into WordPress

Permissions

  • We must always have permission to use images. We must check ALL stock images writers provide us with and ensure they are appropriately attributed + are OK for commercial usage.
    • The only exception is screenshots: it’s ok to screenshot a product UI, a product page, or a web page without permissions.

Intros

  • Don’t include links to studies in short intros.
  • Make sure there are at least two paragraphs in the introduction.

Numbers

  • As a general rule, spell out whole numbers from one to ten, and use figures for numbers above ten (unless it’s a title in a listicle where you will always use the numbered version).
  • If you are writing an article that refers to pricing, make sure it is in the currency of your target audience (e.g., if you are writing in US English, pricing should be in USD). Keep this consistent throughout the whole article: do not mix currencies, especially in comparison articles.
  • When you are writing very large numbers, use a combination of whole numbers and figures.
  • Example: latest figures show 16 million people have now lost their jobs.
  • For numbers that are part of a statistic or percentage, always write them out in numerical format.
  • Example: more than 30% of eCommerce site revenue comes from recommended products.

Oxford comma

  • Always use the Oxford comma.

Paragraph breaks

  • We don’t want to go more than 60-80 words without a paragraph break, and generally, 100 words should be your limit. 
  • Text between 2 headings should generally include two paragraphs as long as the word count is more than 80 words.

Product names

  • Always use the full product name
  • Example: “WooCommerce Product Table” not “Product Table”

SEO and keywords

An SEO section is a bit of a misnomer as, of course, everything we do is focused on SEO! In general, our approach is to make the most useful content possible. The Strategy team have prepared some notes below, although note this is an incomplete list and for specific questions please speak to Strategy.

Excerpts

  • A length similar to the meta description is fine. The excerpt can be slightly longer than the meta description.
  • The excerpt should be unique.

Keywords

  • Our approach to keywords: we need to make sure we signal to Google what we’re writing about. Including target keywords is one of the couple of ways we do this, alongside entity linking. Google is increasingly smart enough to know what the content is about without needing the target keyword included 100 times, so focus primarily on providing a great reader experience.
  • Primary keyword: include this literally once or twice if it’s an awkward keyword. If it’s a natural fit, include it more and use it in a heading!
  • Clearscope keywords: Clearscope is a great way of ensuring we cover topics that people are interested in. We use this alongside data out of FALCON to provide insight into what we need to cover in the content.
    The same rules apply as target keywords: use the topic list as a guide for what to cover, and actively try to talk about as many of the topics as make sense for the content. Don’t, however, compromise on reader experience by using awkward or unnatural topics.
    Clearscope gives you a score, but getting a higher score doesn’t necessarily get us a higher rank. It’s just one way of optimizing content, and we use it alongside many other methods.

Linking

  • Entity linking: we link entities – ie “things” – to their website, so that Google knows what we’re talking about. As a general rule, link up the most important entities we’re talking about to the their corresponding website. You’d link WooCommerce to woo.com, or WordPress to wordpress.org (NOT wordpress.com unless you’re specifically talking about wordpress.com). Other common entities include things like Stripe, PayPal, etc.
    • If Google can better understand what we’re writing about, which the entity links do as they let it connect our content to its knowledge graph, then it can better rank our content!
    • You don’t need to link up ALL entities, just where it will help Google improve its understanding of the content.
  • Always use anchor text across multiple words. Don’t just link text such as “here”. Screen readers need to be able to read the anchor text in isolation and understand what you’re linking.
  • DON’T LINK SPACES BEFORE OR AFTER WORDS!  Never link like this, always link like this.
  • We generally want to link up the client’s product name to a product page. Where we use the product name repeatedly in a section between headings, it’s acceptable to link it only a couple of times.
  • “Naked links”
    • Generally, a link should have quality anchor text. The only exceptions are when you are specifically showing a URL. This is rare.
    • Example of inappropriate linking: “You will be prompted to add your license key. You can find it at https://senseilms.com/my-account/licenses/ once you have purchased a license.” This text should instead read, “You can find the license key under the Sensei account licenses”.
  • We are generous with high-quality links in our content. Links to high-quality websites and sources enrich our content by providing high-quality additional sources for readers to enjoy. Just make sure the links are high-quality!
  • Avoid linking to a third-party site with anchor text that matches our target keyword.

Meta description

  • FALCON AI will output a meta description. By default, use this. You’d choose to differ if we’ve substantially changed the contents of the post.
  • Always keep meta descriptions under 160 characters. You can easily check this on www.charactercountonline.com.
  • Use the focus keyword and a call to action, summing up the main points in the article.
  • Make sure it is aligned with search intent and matches what the article is actually about!

Specific words

  • Refer to the Ellipsis A-Z for specific words and spellings.

Underlining

  • Avoid using underlining within any copy. Instead, use bold formatting for emphasis, or italics to differentiate words from the rest of a sentence.

WordPress

  • Automattic makes WordPress.com, not WordPress.
  • WordPress, WooCommerce, etc, must always be spelled CamelCase (see A-Z for more)
  • Plugins vs. coding
    • It’s not generally a feature of a plugin that it’s easier to use a plugin than it is to code it yourself. This point is true, but it’s also incredibly obvious and a feature of all plugins. Content about buying a car wouldn’t tell you that it’s easier to buy a car than to build one yourself. Very few readers are genuinely comparing getting a plugin with coding themselves, so we should not rely on this point.

Writing in Google Docs (for writers)

  • Always use proper headings, even when using GDocs. Don’t just use bold text as a heading: use the proper heading 2, heading 3, etc.
  • Always include:
    • Meta description at the top of the doc.
    • ALT text underneath any images.
Updated on June 10, 2024
Was this article helpful?