Style Guide

So you’re writing for our blog. Awesome!

However, putting together articles is not all WordPress skillz and witty turns-of-phrase. There’s a lot more to it as this style guide shows.

Please study these guidelines and refer to them when necessary.

Posting Checklist

Headings/Sub-Headings – Make sure they are short, literal, error-free, catchy and click-worthy. Headlines are also likely to be changed during the editing process. Read more.

Category – Choose a maximum of three categories, though you may only want to use one.

Tags – Choose a maximum of five tags.

Feature Images – Our designers create custom featured images for all our posts, so you don’t have to worry about inserting one. Read more.

Custom Excerpt – Create a brief and concise custom excerpt that will draw visitors in from search engines and social media sites. Read more.

Styling Posts – Use short paragraphs, bullet points and blockquotes to break up big chunks of text. Read more.

Style and Grammar — We follow US English and use the Yahoo Style Guide, albeit loosely.

Styling Images – Use images for instructional purposes or to break up text and provide a more interesting reading experience. Read more.

Embedding Videos – Use videos to add another visual element to your posts. Read more.

Social Media – All posts are scheduled to go out to our Facebook, Twitter and Google+ accounts. You don’t need to worry about updating WordTwit in the Post Editor. Read more.

Social Media Profiles – Make sure your Google+ profile lists you as a contributor to the WPMU DEV Blog. Read more.

Related Posts – Check that the related posts are relevant. Read more.

Code Snippets – Use Gist for all code snippets. Read more.

In-Post Ads, Front Page Excerpt, Infinite SEO – You don’t need to worry about these settings.

Custom Posts – We have three custom post types – Lists, Reviews and Comparisons. Read more.


Headings/Sub-Headings

Focus the title of your post. If you don’t write your title to be accessible to search engines (under 70 characters with the main keyword near the front of the title), you can insert an optimized title into the “Infinite SEO” meta box.

The meta box allows you to add a search engine accessible title – we want to make sure Google users get the best possible experience. Search engines will see that title as will search engine users. So make it both accessible and extremely reader-friendly as well.

Having said all this, post titles are likely to be changed during the editing process, so please don’t update the information in Infinite SEO.

Your original title (not the one in the Infinite SEO box) will be seen on our blog, as well as in in RSS feeds, on Facebook, Google+, Twitter, etc. This means it’s important to make your title human readable. Try to entice readers into the post with your title.

While making your title accessible to search engines is less important in the original title, you should also try to include your keywords in it if possible (or variations of your keywords — write for humans first). Search engines will pick up links from that title out on social media sites, and so it’s important to tell them what the post is about. It’s also important that this title has at least one word in it that is WordPress-related, such as WordPress, BuddyPress, Multisite, plugins, themes, etc. This will help people who are looking for WordPress info to identify your post as something WordPress related.


Feature Images

Mountain
Custom feature images are created for each post.

Our designers create tailor made images for all our posts, so you don’t need to set a feature image.

For reference, the dimensions for feature images are 735px by 210px.


Custom Excerpt

Entice readers with a short and sharp excerpt. It’s an important piece of text because it’s seen on search engines and social media sites like Facebook, Twitter and Google+.

Excerpt
Create a custom excerpt for all your posts.

Styling Posts

Ensure your posts are easy to read by breaking up text into smaller chunks. Keep in mind that people often scan text on the web rather than read long paragraphs.

You can break posts up in a number of different ways. Use the following:

  • Images
  • Sub-heading
  • Bullet points or numbered lists
  • Bold or italicized text
  • Blockquote
  • Short paragraphs

People are used to reading much shorter paragraphs on the web compared to paper. Therefore, don’t be afraid to break a traditional paragraph up into several smaller paragraphs of a 1-3 sentences.

First Paragraph of Post

The first paragraph of a post must be wrapped in <h2> tags. This is a new feature of our website design.

Sub-Headings

Sub-headings within posts should use <h3> tags. Please don’t use <h2> for any sub-headings. Any sub-headings contained within <h3> tags should use <h4> tags, and any further sub-headings should be made bold.

Comment Prompt

At the end of every post, please pose a question to readers to encourage comments, and make it bold. For example:

Have you done any mods to your WordPress editor? Did you use code, plugins, or both? Have you used these or any plugins that I didn’t mention? Let us know in the comments below.

More Tags

Add a <more> tag after the first three or four paragraphs of your posts. This will ensure subscribers who receive daily blog updates will receive a short update about your content rather than the full post.

Exclamation Marks

Please refrain from the excess use of exclamation marks. An editor once said to me, “Everyone is entitled to two exclamation marks during their life time. Use them well.”


Styling Images

Use images to illustrate a point (a picture tells a thousand words!) and to provide a more interesting reading experience.

Use a mix of images and alignments where possible. If you are trying to illustrate something important, you may want to use a large image (700px). You may also use a fullwidth supersize image, but only if the image is impressive and high resolution. If it’s not an overly impressive image, you may choose to make it much smaller and wrap text around it.

Using the Custom Media Uploader

Custom media uploader.
Our custom media uploader. This is also an example of the 2:3 ratio in action with the caption underneath. You can see that the image takes up 2/5 of the column, and the text from the post wraps around it and takes up the remaining 3/5 of the column.

You will notice that our media uploader is not exactly like the default WordPress uploader. When you click “Add Media,” in the Post Editor, you will see our media uploader (see image to the right).

The Image Variation field determines where you want the image to appear. Supersize (fullwidth) and Large (735px) images are always centered. Captions for both appear under the image.

When you choose to align an image to the left or to the right, however, you are offered a number of other choices.

Position and Image-to-Text Options

The first choice is the image-to-text ratio.

The 1:4 ratio takes up 1/5 of the space in post column. The other 4/5 of the column is occupied by text.

The next choice you’re offered is whether to place the caption directly under the image or to the side of the image.

If you choose to place the caption directly under the image, then 1/5 of the column will be occupied by the image with the caption underneath it. And the other 4/5 of the column will be occupied by the text of  your blog post.

If you choose to place your caption to the side of the image, however, then 1/5 of the column will be occupied by your image, and the other 4/5 of the column will be occupied by your caption (and not the text from your blog post).

Check out the image on the right for an example of how the 2:3 ratio works.

And of course the aligned left position works the same way, except reversed.

The three basic alignment positions (left, right, centered) work as you would expect them to, except you can place captions beside an image, not just underneath.

You may notice that captions looks a little strange out to the side if you don’t have a lot of caption text, so take that into consideration when deciding your image alignment.

Image Sizes

All images uploaded to the blog should be of 735px wide. All images. Any images that are larger than this will not display correctly. Even if you plan to use one of the alignment options, such as 2:3 or 3:2 to display the image, you should still upload an image that is 735px wide.

If you want to use an image that is smaller than 735px, it’s still fine to use, but choose an appropriate ratio to display it with so it looks good.

Fullwidth Images

The option for fullwidth images should only be used for images that are high resolution. This option should not be used for boring images!

To implement a fullwidth image, use this shortcode:

You can also add a quote to display over the top of the image:

And here’s what it looks like:

At Spirit’s core is Upfront, an incredibly powerful drag and drop

theme builder designed to help you create the website you want with ease.

An opaque overlay will soon be added to this feature to make quotes stand out. Stay tuned.

Cropping images

Ensuring your images are no wider than 735px can be difficult to achieve when taking screenshots. The best way to do this it to make your browser window smaller (CMD + – on iOS) before taking a screenshot.

Note: Please avoid taking a large screenshot and reducing its size as this also reduces image quality. For example, if you take a screenshot that is 1000px wide, don’t open it in Photoshop and reduce it to 735px. 

If making the browser window smaller isn’t an option, take a screenshot of a section of the screen instead:

Network requests
Screenshot of the network requests shown in Google Chrome Developer Tools.

This image is 513px by 299px and while it’s smaller than the required 735px width, it’s clear to read and the text isn’t too small.

If you must use a large screenshot to appropriately illustrate the functionality of a product or service, it’s okay to upload the image to your post, but make sure the image links to its own URL in the media library. This will allow readers to access a larger version of the image. In the image caption, add: “Click to see a larger image.”

Make Images Accessible

Add descriptive file names and alternative text to your images to ensure they are accessible to text/screen readers.

File Name

Name your image something appropriate. The name of your image file will also automatically become the title of your image in WordPress. Therefore, don’t name it something like “pic0000324987.” Name it something appropriate such as “youtube-featured-video-popup.” If you are using an image that contains text, save your image as a PNG file to ensure it doesn’t blur the text.

Alternative Text

Alternative text, also known as “alt text,” is an opportunity for you to describe your image in a short sentence or phrase. When you do this, think of how you would describe your image (in the context of your post) to someone who is visually impaired.

Screenshots and Annotations

No doubt you will need screenshots in your posts. If you don’t have a tool to do this already, Jing is free software you can use.

In order to highlight an area of a screenshot, please use a yellow outlined shape such as a yellow square or a yellow circle. Please do not use arrows or shadows.

Add new listing to custom taxonomy.
An example of how to correctly highlight an area of a screenshot.

Ensure Images Are Not Linked

When adding new images to a post in the media library, make sure it doesn’t link to another website or its own URL:

Link to none
Ensure your images don’t link.

This is especially important for posts that use the custom and review list post types.

Image credits

Make sure any images you use other than screenshots are free to use and available for commercial purposes. If you are using an image and not sure if you are allowed to use it, find its original source and check the license. If you can’t find any licensing information, don’t use it.

Check out The Best Places to Find Free Stock Images for Your WordPress Site – our guide to free stock images – for a list of some fantastic stock image sites.

You may need to provide attribution for any images you use from free sites, depending on licensing. Please display attribution at the bottom of your post like so:

Image credits: Unsplash, Picography.


Embed Videos

Videos should be embedded in posts using iFrame. When embedding videos from Wistia, for example, choose “iFrame” under embed type:

Embed videos
Ensure your videos are a maximum width of 735px.

Under “Video Size,” the maximum width should be 735px. The height of the video is up to you. After you embed your video, preview how it looks on the blog and edit the video size in the Text Editor to ensure it has appropriate dimensions.


Social Media Profiles

If you don’t have a Google+ profile, please get one and connect it to premium.wpmudev.org/blog. Here’s how to do it:

In the premium.wpmudev.org/blog admin area, go to Users > Your Profile > Enter Your Google+ URL (for example, our CEO James Farmer would use: https://plus.google.com/100867129079471807437/posts).

In Google+, add premium.wpmudev.org/blog to your profile by going to the About section in your profile and in the “Links” section click “Edit.” Then in the “Contributor to” section add premium.wpmudev.org/blog


Related Posts

Related posts need to be, well, related. Unfortunately, YAARP doesn’t always pull up the best related posts and can list posts that have been 301-ed and/or no longer exist. So it’s important to check the suggested related posts that appear in YARPP.

1. In the Post Editor, scroll down to the bottom to the Related Posts section and check out each of the posts that are listed.

YARPP
Check related posts are relevant.

2. Uncheck any posts that are irrelevant, old or have been 301-ed.

3. Search Google for topics similar to what you have written about in your post. For example, if your post is about popular post plugins, search for “site:premium.wpmudev.org/blog popular post plugins.”

Relevant posts
Search Google is YARPP doesn’t display any appropriate posts.

4. If any of the posts listed in Google search are a better match for your article, copy the post’s URL into the “Enter your post URL” text field and click “Add.”

5. Once you have three related posts you are confident are relevant and complement your post, click “Save and Publish This Selection.” Make sure you save your selection otherwise the links will be wiped next time you save your post.


Code Snippets

There are two ways to use code within a post: within a paragraph to make a point about code that is being discussed, or as a highlighted block of code.

Code Within Paragraphs

Use the <code> tag to distinguish text that is computer code and not natural language.

For example, when writing about a WordPress function like wp_title(), switch to the Text Editor and wrap the function in <code> tags.

Blocks of Code

For longer blocks of code, use Gist to ensure your code displays correctly and the Post Editor doesn’t strip any characters.

If you haven’t used Gist before, it’s a simple way to share snippets and pastes with others. All gists are Git repositories, so they are automatically versioned, forkable and usable from Git.

Create Gist.
Create a new Gist.

To use Gist:

  1. Go to Gist and sign up for an account.
  2. On the Gist main page, give your code snippet a description and a file name, then select a language for your code.
  3. Paste your code snippet into the text area.
  4. Click “Create public Gist.”
  5. On the next page, copy the URL for your Gist.
  6. Paste the URL into your post where you want your code snippet to display. Ensure the URL doesn’t have any formatting.

The resulting Gist code snippet will look like this:


Custom Post Types

We have three custom post types for displaying content on the blog:

Lists

The List post type provides a neat way to display plugin and theme lists, as well as lists of other products and services.

List post type.
The list post type.

To create a new list:

  1. Go to Lists > Add New.
  2. Give your list a title.
  3. Add a feature image. All feature images must be 735px by 210px.
  4. Add a description for your list item in the main text area.
  5. In the “Buttons” section, name your button and than paste in a URL. Generally, it’s best to name the button “Details” unless you want to be more specific or you need more than one button. For example, a theme post may have buttons for “Details,” “Demo” and “Download.”
  6. To add another item to your list, click “Add New List Item” at the bottom.
  7. When you’ve finished creating items for your list, click “Publish”.
  8. Copy the shortcode that is generated below the “Publish” button and paste it into your original post where you want to display your list.

Your list will look similar to this: 50+ Quick Setup Portfolio WordPress Themes.

Reviews

The Reviews post type provides a way to display in-depth reviews of products and services complete with star ratings, and our opinion of the good and bad aspects of a particular product or service.

Review post type.
The review post type.

Creating a review is similar to creating a new post.

To create a review:

  1. Go to Reviews > Add New.
  2. Give your review a title.
  3. In the post area, write your review.
  4. At the bottom of the Post Editor, fill in your review information with Good, Bad and Bottom Line information.

    Review information
    Provide Good, Bad and Bottom Line information for your review.
  5. In the Review Ratings section, give the product/service you are reviewing ratings out of 10. These will be converted to ratings out of five when displayed as stars on the blog.

    Review ratings
    Give your review star ratings.
  6. When you’ve finished your review, click “Publish”.
  7. Copy the shortcode that is generated below the “Publish” button and paste it into your original post where you want to display your review.

Your review will look similar to this: Drag and Drop Review Redux: Divi by Elegant Themes.

Comparison

The Comparison post type draws information from the Reviews post type and is used to create a table comparing several reviews.

Check out Choosing a WordPress Theme Framework – the Ultimate Guide” and scroll to “Theme Frameworks Compared” at the bottom of the page to see the Comparison post type in action.

To create a comparison:

  1. Go to Comparison > Add New.
  2. Under “Comparison Items,” enter the names of the reviews you want to compare. When you start typing, the field will ask you to autocomplete. Click “Add” to add the review to your comparison.

    Comparison items
    Add reviews to compare.
  3. The “Comparison Reviews” section allows you to compare each of the reviewed produces/services against each other and give them ratings out of 10. You can add open or more review ratings sections, depending on how many elements you would like to compare. For example, if you are comparing several theme shops on their prices, usability and support, you would add comparison ratings for “Prices,” “Usability” and “Support.”

    Copy the shortcode at the bottom of the section and paste it into your original post.
    Copy the shortcode at the bottom of the section and paste it into your original post.
  4. The “Comparison Overall” compiles all of the ratings you have entered in the other sections and produces a table with an overall rating for each reviewed product/service. Here, you can specify how many columns to display the resulting table.

    Comparison overall
    The comparison post type create an overall table comparing products/services you have reviewed.
  5. For each section, copy the shortcodes that are produced and paste them into your original post. Preview your post to ensure they display correctly.