Style Guide

GV Style Guide and Posting Guide

Welcome to the evolving GV Wiki style guide.

NOTE: The most updated version of the style guide is 2011 Style Guide. We are working to harmonise both versions.

Post Types

GV has two primary kinds of post: Stories and Updates

Stories (weblogs) are displayed on the left section of most pages on Global Voices. We show a short excerpt on the listing and the full article on its own page. Any author at GV can post a Story article. Typically, the Story entries are detailed explanations of one big idea or several related ideas. They generally make use of links, quotes and images from many different blogs about the subject covered.

Updates (roundups) are what we call short link posts that basically just link to an article that an editor thought was interesting. Roundups appear in the right column of most pages with just their text, permalink and author listed. Only Regional Editors post to this section. Usually an Update is a line or two of commentary on a post/blog/project with one or two links to it integrated in the text.

NOTE: The rest of this document will discuss the WEBLOG type of post. For guidelines and advice about the short Update posts see this page: Style Guide Roundups

Post Title

It's a good idea to provide an overall idea of the post in the title itself.

It's generally a good idea to provide a little geographical context to the entry. Not everyone knows that Blog X covers country Y. So you could say "the Scotland-based blog What's Up, Pussycat points out that ..." Also, please remember that not everyone reading your writing will be as familiar with the geography that you're covering as you are. For example, "There was celebration in Vaduz, the capital city of Liechtenstein, as..." is far better than "There was celebration in Vaduz, as..." Likewise, "Reports out of the tiny Italian city-state of San Marino indicate..." is preferable to "Reports from San Marino say that..."

Adding Images

TODO

Thumbnails and Featured Images

In the GV theme there are two kinds of special "thumbnail" images that are shown along with post excerpts and titles in the archives. Adding thumbnails and featured images to your posts isn't mandatory, but they really make your articles look nicer and more exciting in the list, so its worth spending some time making sure there is always an image associated with your post.

Thumbnails

Choosing a thumbnail from the post editing screen

Thumbnails are the small 100px by 100px images that show in all archives next to the post excerpt. Setting a thumbnail for your post is easy. Once you have uploaded some images to your post you just need to go to the GV Post Thumbnail Chooser box below the post content box and click on the thumbnail you want to use. Once you save the post that thumbnail will be chosen.

If you want a thumbnail that isn't an uploaded image you can enter the url directly in the box below. Be careful though, in most cases it is better to upload the image and use the uploaded version just to be safe.

Sometimes a thumbnail doesn't look good because the things in it are too shrunken. If this happens you should try to crop the image so that only one small interesting part of it is showing. You can do this with an editor on your local computer then reupload the image. You can also use the image editing tool inside the WordPress uploader, though you should re-upload your image before doing so to avoid changing the original image that you inserted into a post.

Featured Images

The Featured Image box showing the selected image

Featured images on GV are similar to thumbnails but much larger (300px by 300px). They are only used if the post is featured and showing in the blue features box on the homepage. It might not be shown but you can add a featured image to any post you want, we may start using them more often in the future!

To add a featured image use the Featured Image box in the sidebar of the post editor:

Click "Add Featured Image" to open the image uploader popup.
Either upload a new image or go to the Gallery tab at the top to see a list of photos you already uploaded.
If you are using an already uploaded image click the "Show" link on the right to view its settings.
At the bottom of the settings click the link that says "Use as featured image".

Detailed settings for an image and the Featured Image link

That's it! You should now see the image in the sidebar, and if your post is in the features cycler then this image will be shown.

Adding Video to Posts

We don't usually create original video at Global Voices and our site is not set up to actually host custom video. We do however encourage you to include embedded YouTube (and similar sites) video when it is relevant to your story.

Note that because YouTube videos (or any other embedded content) can be deleted at the source you should always include a brief explanation of what the video will be, that way if a visitor sees an old post with a broken video they at least know what the video was supposed to be about.

Embedding YouTube videos

Embedding a YouTube video is easy, but it's important you do it the right way. The HTML code you can copy on the YouTube site is very finnicky and can break when viewed in the Visual Editor and/or when it is imported for translation. To avoid this issue you should always use the simplified WordPress Embed system.

See the WordPress Codex article about Embeds

The process is simple, just get the URL of the video/object you want to embed and paste it into your article on it's own line, like this:

Here is a video that illustrates my point:

[embed]http://www.youtube.com/watch?v=k0jNwMR9FiM[/embed]

There you have it, what a great video explanation!

This system is great because if the video or the embedding system ever break your visitors will still see the link to the video!

It will still work if you skip the [embed] and [/embed] tags, but if the embed ever stops working those tags will help visitors understand what you expected them to see.

Embedding other kinds of Video

The YouTube embedding system is actually very general (based on a standard called oEmbed), and a lot of other kinds of videos can be embedded the same way.

The full list is very long but here are some of the popular services that should work with the [embed] tags: Vimeo, Flickr, DailyMotion, Viddler.

If you try the [embed] method and it doesn't work then you can use whatever HTML the video site gives you for embedding, but please be careful and make sure that the embed code works well with our WordPress install.

Note on the Visual Editor

When editing a post in WordPress there are two editors, the HTML editor which shows you the raw code and the Visual editor which shows you what the post will look like (WYSIWYG, What You See Is What You Get).

The Visual editor is very useful but it often breaks complex HTML like video or other embed codes because of the ways that it filters content.

When the Visual editor breaks a certain kind of embed code you can avoid the problem by just not using the Visual editor but this is not a good idea! At some point someone will try to edit your post with the visual editor, and suddenly all the embeds will dissappear! Lingua translators usually use the Visual editor too, so if your embed code doesn't work in the Visual editor then people translating your posts will be very confused.

So please test any custom embeds with both the HTML and Visual editors before publishing your post!

If the embed just won't work

If an embed does not work with both the HTML and Visual editors (or if it doesn't work with either) you can always just take a screenshot of the video/thing and embedding that in your post instead. Add a link to the video/object on it's homepage to the image so that when people click it they will be taken to the video. For bonus points get a screenshot with the big "Play" button visible, so that people click it before they realize it's just a screenshot ;)

That is a foolproof method when things get too complicated, and is not likely to cause any problems during saving or translation.

Universal Subtitles

The GV sites have support for embedding videos with Universal Subtitles support so that they can be subtitled by translators. This uses the normal [embed] system, but with the unisubs attribute set to 1.

Example:

[embed unisubs="1"]http://www.youtube.com/watch?v=k0jNwMR9FiM[/embed]

Note: Currently Universal Subtitles is unable to handle the YouTube short URLs with the domain youtu.be. You must always use the full youtube.com version of the URL instead.

Text styles in Posts

Linking to automated Google Translations of a URL

In many cases Google Translate can automatically generate usable translations of a URL, depending on the source and destination language and the text. In some cases, it may be desirable to add a link to your post that will take a reader to a translation of a URL you are discussing into their language (i.e. linking to the English translation of a Russian article on an English post).

These links can be complicated to put together and cannot just be copied from your address bar though. If you have your link auto-translated then copy/paste the URL from your browser it looks something like this, and it won't work:

http://translate.google.com/translate?js=y&prev=_t&hl=ru&ie=UTF-8&layout=1&eotf=1&u=http://www.nn.by/index.php%3Fc%3Dar%26i%3D32806&sl=be&tl=en

Adding that link to the post won't work.

Instead, you can easiliy create a Google Translate URL For the source URL using their special format:

http://www.google.com/translate_c?langpair=SOURCE_LANG%7CDESTINATION_LANG&u=SITE_URL

This format has three parts that you need to fill in, shown in ALL CAPS above:

SOURCE_LANG - The language code (en,fr,ru) for the language of the document you are translating.
DESTINATION_LANG - The language code (en,fr,ru) for the language you want the document translated into.
URL - The URL of the document you want to translate

So for example to link to a translation of http://www.kiva.org/ from English to French you'd use this URL, with 'en' for english, fr for french and ending in the Kiva URL:

http://www.google.com/translate_c?langpair=en%7Cfr&u=http://www.kiva.org/

Google doesn't support all languages, you can find the list of supported languages here: http://translate.google.com/

If you're not sure about the language code (en, fr etc.) for a language that Google supports you can find a full list here: http://www.loc.gov/standards/iso639-2/php/code_list.php

Marking Dead/Inactive Links

Links on the internet die sometimes. On GV we do a lot of linking and sometimes you will notice that a link has stopped working on an old post. If you can find the same article at a new link, then replace the old link with the new one and resave your post. If you can't find the original post you should mark the link as dead with the <del> html tag (which is in the editing buttons in Wordpress) and add a brief note about the dead link.:

<a href="http://url.com/postlocation/">

becomes

<del><a href="http://url.com/postlocation/"></del> [dead link]

Which will show the link with a line through the middle of it, like ~~this~~.

In any case, please use the Edit Request form to inform the Editors of the Lingua sites, so that the translated posts are also dealt with.

Listing Contributors (other than the author)

We use the 'contributors' class to denote people who helped create a post but aren't the main author (because there can only be one author in Wordpress). This could be someone who helped translate the post for you, did a lot of editing, or anything else.

You should always put the 'contributors' paragraph at the end of the post so that it will match the author credit just below it and make them look similar. '

You can use the 'contrib' button in the editor to make some text into the contributor paragaph or you can type in the code yourself, it looks like this:

<p class="contributors"> TEXT HERE </p>

If you are listing the name of someone who is part of Global Voices, as always please link to their GV profile page (like this one) so that people can find their posts and bio information easily.

Extra Notes

To add some visually distinguished notes at the beginning or end of a post please use the "notes" class in a div around your content. Translation notes can be used to add necessary context or information for your linguistic audience:

 <div class="notes">Notes: This post is being ironic.</div>

Site Names

Site names should be in italics; e.g. "I think that Global Voices is a really interesting blog" or "There was a really funny podcast on Global Voices yesterday."

In the unusual case where a blog or a site appears to be unnamed, use the the domain name or the blogger's name e.g. "Over at www.wrycatcher.com, Holden Caufield writes that..." or, alternatively, "Holden Caufield, on his blog, writes that..."

The names--or nom de blogs--of bloggers should be in normal type. This also applies to bloggers who are not anonymous but are commonly known by their nom de blog, e.g. Instapundit or Atrios or mr.brown. When a nom de blog is synonymous with the site itself--again, e.g. Instapundit--there's no need to italicize the name. The only exceptions are if

1. you're specifically writing about the site itself and need to distinguish it from its creator. E.g. "Is Instapundit the site more important than Instapundit the man?" or

2. the post you're linking to was written by a guest blogger: "Jane Smith, guest-blogging on Instapundit, writes that...". Even then, you can get around it by writing something like "Jane Smith, who's guestblogging for the Instapundit this week, says that..."

Titles of Individual Posts

Titles of individual posts should be in "quotes". E.g. "in a post titled 'Why Whales?' in his blog The Pequod, blogger Ishmael explains why he decided to go to sea."

NO UNDERLINES!!

Feel free to use Italic text or Bold text to create emphasis in posts. However, please do not use underlines, as that usually indicates a link and could be confusing for readers.

Picture Posts

For the title, use "Images from Countryname: Short Descriptive Slug". For example, "Images from Canada: Pancake Factory" or "Images from Hong Kong: Dim Sum Palace".

Make sure that the image you want to post has a Creative Commons license. This is very, very, very important. In case the image doesn't have a CC license and you are very keen to use it, you could email the owner of the picture and get permission as well.

A short caption at the bottom of the image, after the byline, can be very useful in providing clarifying context, particularly if the subject matter of the image isn't self-evident.

Download the images from Flickr/ Any other site that hosts the photo: click on the 'All Sizes' button above the image to get the largest, highest quality images. Resize the image to no more than 350 pixels wide, then upload it to GV.

Here's some sample HTML you can use:

<div align="center"><a href="LINK TO ORIGINAL PICTURE"><img border="0" src="FULL PATH TO IMAGE" style="padding: 10px;" /></a></div>

<i>"TITLE OF PICTURE" by <a href="LINK TO PHOTOGRAPHER'S PHOTOSTREAM">PHOTOGRAPHER'S NAME</a></i>