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 (and Cropping and Compressing Them Properly) – 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

Blog feature image
One of our awesome feature images!

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

Blog exceprt
Enter a short, two-line excerpt that summarizes your post.

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


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

First paragraph
The first paragraph of every post must be styled.

The first paragraph of a post must be wrapped in <h2> tags.

This is a new feature of our updated website design that helps to draw readers into the article.

It also helps to quickly emphasizes what the post is about for our readers who simply skim the content, rather than read it in-depth.

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 (and Cropping and Compressing Them Properly)

Use images to illustrate a point (a picture tells a thousand words!) and provides 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, rather than a regular image, for example. You may also use a fullwidth, but only if the image is impressive and high resolution enough.

Using the Custom Media Uploader

Image variation

We’ve customized the media uploader to suit our blog design.

There are eight images variations to choose from and you must upload an image with the corresponding width. Any height is fine (except for left/right images), as long as it doesn’t look ridiculous.

Regular – 735px

These images sit inline with the blog content. Here’s an example:

Related posts
An example of a “Regular” image.

Large – 1364px

Large images take up more of the screen, though should always be 1364px. Use this size if you need to show a bit more detail in your posts.

Large image
This is an example of a “Large” image.
Left aligned
A left-aligned image.

Left – 490px x 312 px

Left aligned images can further enhance the reading experience.

When adding a left aligned image, the image uploader will create a table. Make sure you delete the placeholder text and write just enough of your own to fill the space next to the image so the last line sits almost flush with the bottom of the image, like so.

Right aligned image
An example of a right-aligned image.

Right – 490px x 312px

Right-aligned images are just like left-aligned images except they’re, well, on the right.

Don’t forget to replace the placeholder text and enter enough text so it almost sits flush (give or take a few pixels) with the bottom of the image. It just looks better!

Fullwidth – 1364px

Now this is where things really start to get interesting. Fullwidth images are just that – fullwidth. Here’s an example:

Fullwidth dark bg – 1364px

There are also a couple of variations on the fullwidth image. The first offers a dark background, over which you can enter some text. You may want to enter a blockquote or just some interesting information you want to highlight.

When you upload an image, the text that’s shown over the top will be pulled in from the caption you write. In the backend of your post, the image will be displayed with a shortcode and you will be able to edit the displayed text.

The text below has been styled as a blockquote:

`Twas brillig, and the slithy toves
Did gyre and gimble in the wabe:
All mimsy were the borogoves,
And the mome raths outgrabe.

Fullwidth light bg – 1364px

There’s also a fullwidth variation with a light background. This may come in handy if you have a dark image over which you wish to place some text.

Cropping Images

While the image below doesn’t meet the dimension requirements for our blog, I’m using it as an example of how magnifying a select part of an image can help illustrate a point.

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

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” or “Screen Shot 2015-07-20 at 6.29.57 pm.” Name it something appropriate such as “youtube-featured-video-popup.”

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.

Image Compression
By Victor Ivanov, WPMU DEV Product Guy

This is a quick re-fresher course on best practices for using images on our blog. The steps below are for Photoshop, but you can achieve the same results with any image software.

It is incredibly important that we follow the rules below for two reasons:

  • Our images should always look as good as possible. We make legit, high-quality products, and our marketing assets need to reflect that.
  • Our awesome developers spend a lot of tim making sure wpmudev.org is super, super fast. Uploading huge, poorly compressed images essentially negates all their hard work.

1. Choose a Format Suitable for the Image

Here’s an example of a poorly compressed image: http://premium.wpmudev.org/blog/wp-content/uploads/2015/06/wp-optimize.png

It’s 342kb, which is outrageous for image of this size. The reason here is that the PNG format is not suitable for this type of image.

Here’s rough rule of thumb: Use JPGs for photographic images, and use PNGs for images with a limited number of colors.

For example, a picture of the WordPress admin, a paragraph of text or an illustration with a few colors should be a PNG, whereas an iPhone photograph of your dog catching a frisbee whilst doing a backflip should be saved as a JPG.

If you’re not sure whether to use JPG or PNG, just test what looks best without generating a massive filesize. It’s really easy and you should pretty much become an expert in the first few tries!

So coming back to the aforementioned image, you can see that there is quite a lot of photographic detail (the noisey bg). I saved it as an 80% Progressive JPEG and managed to cut the size down to 90kb from the original 342kb. That’s about 3.8x smaller and the best part is the quality difference is imperceptible.

2. ALWAYS Follow Our Image Sizes Guide

Again, our superb developers have actually added image variations  into the Media Manager UI. It is impossible to miss.

You should always save and upload images at the corresponding sizes. Doing so ensures that WordPress will not automatically re-size and compress the image further resulting in poor quality. An exception here can be made for animated GIFs, as those can be quite tricky to get the exact size.

3. Always Save As PROGRESSIVE Image

Progressive images are faster, smaller in size and are just better. They are a clear win-win.

Progressive images first load pixillated and over time, become clear. This is also a win because this creates an illusion of super fast page (as well as actually making page faster). Perceived performance is probably even more important than actual performance. Here’s a gif that demonstrates Progressive JPEG load: http://media.mediatemple.netdna-cdn.com/wp-content/uploads/2015/06/13-progressive-jpeg.gif

That’s basically it. The third rule is new, I have not mentioned it before, but it is super relevant and we should all be using it. Also, I realize not everyone uses Photohsop, but I am certain that any decent alternative graphics software should also have all those Save For Web settings.


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.