Style Guide

Introduction

This page will describe what style conventions should be followed when creating, editing or migrating content to this site. Adhering to these rules will give the site a consistent look and feel, ease the creation and modification of content, and get your content or changes published as quickly as possible.

You should read the Markdown Guide before this page, and probably the Content Authoring Guide as well. This page assumes you understand Markdown.

General Guidelines

  • Avoid HTML where it is not necessary. A full page of HTML will not be accepted, even if it is a page that you are migrating from the old server. You will need to learn Markdown; thankfully it is not very difficult.
  • That said, some HTML can be useful, especially if Markdown is not powerful enough to express what you are trying to do.
  • Use spaces for indentation, not tabs; tabs are annoying to input in the text boxes in most browsers, and don't show up the same everywhere. Four spaces is one level of indentation (i.e. for creating code blocks).
  • Where the style guide leaves you a choice, follow the convention of whatever page you are editing (or if you are creating new content, pick a convention and stick with it throughout the page).
  • Write content so that it is easy to read and edit. That is the entire purpose of this style guide.

Common Spelling/Capitalization Variants

  • Go is not a proper noun, and thus is not capitalized (unless the rules of English otherwise require it of course, such as at the beginning of a sentence, or inside a title).
    Examples:
    • "...the game of go..."
    • "American Go Association"
  • The word "online" is one word, no hyphen, and not inherently capitalized.
  • The word "email" is one word, no hyphen, and not inherently capitalized.
  • The word "internet" is not inherently capitalized.

Headers

  • Use headers only to mark the beginnings of different sections of a page.
  • Never use headers just because you want some text to be big and important looking. Use the emphasis marks for that: important text.
  • Always start with the biggest headers for your main sections on a page.
  • Subsections inside of those main sections get the next smallest headers, and on down.
  • Do not skip a header level
  • Sections that are at the same level all get the same header size
  • Headers should not be very long. Around five or six words is the max, and even that should be rare.
  • Put a single space between the #s and the header text, it looks nicer. If you specify a header ID attribute, put a space before that as well.

Page Titles and Headers

Page titles and headers are in Title Case. There are many different, mostly similar versions of title case, so let's just go with the writersblock.ca title capitalizaton guide:

  1. Always capitalize the first and the last word.
  2. Capitalize all nouns, pronouns, adjectives, verbs, adverbs, and subordinate conjunctions ("as", "because", "although").
  3. Lowercase all articles, coordinate conjunctions ("and", "or", "nor"), and prepositions regardless of length, when they are other than the first or last word.[..]
  4. Lowercase the "to" in an infinitive.

See the link above for examples. Nobody will bite your head off if you're a little wrong, but try your best.

Text Wrapping

Do not manually wrap text inside a paragraph. Doing so makes it annoying to change lines as you either need to manually rewrap the entire paragraph, or you leave unsightly shorter or longer lines.

In case you do not understand what this means, do not manually hit the "enter" key to go down to the next line when you run out of room in the text box within one paragraph. Instead, just keep typing and the text box will automatically "wrap" you around to the next line.

It is up to you if you manually wrap text that is in lists or not. If you do manually wrap inside lists, indent the text to the same level as the start of the list item, like so:

* I am a very very very long list item,
  that is continued on the next line.
* The next list item

Remember to pick one convention and stick with it inside one page, and follow the convention already used in a page if editing.

If you do manually wrap anything, do so at 80 characters or so, and stick with a consistent maximum line length.

Link Text

  • Your link text should describe what you can find at the destination, not give the user instructions on what to do or anything like that.

    Bad style: click here to go to our events page.

    Good style: You can find out more on our events page.

    Also bad: here, download, etc.

    You may have to reword your text a little bit to make this work, that is expected. Don't be lazy; it's important.

  • Ideally the link text should include some keywords from the title of the destination page or the content of the destination page

  • Good links are easy to scan for, you shouldn’t have to read the surrounding context to figure out what you will find at the destination.

    People don’t read web pages like a book, they skim and jump right to what they want. If that’s difficult, they’ll find it annoying and go somewhere else.

    If you're having trouble, look only at the text of the link in question, not at any surrounding context. Is it easy to tell what you'll find if you click? If so, you're probably doing alright.

  • Keep link text to about four words or less, no paragraphs.

Specifying URIs (for links, images, etc.)

  • Always test your URIs and make sure that they actually work. Ideally, make sure that they do not redirect as well (as that will slow down page loading).
  • During the migration period, act as if usgo.org was the domain on migrated pages, not the temporary test domain usgo.emptypath.com. This makes a difference when deciding between external/internal identifiers in the rules below.
  • External identifiers must always include the protocol.

    Good style:

    [A link](http://www.example.com/)
    

    Bad style (doesn't even work as you might expect it to actually):

    [A link](www.example.com/)
    
  • Internal identifiers (on the same domain) should usually be relative to the document root

    Good style:

    [A link](/somewhere/overthere/)
    

    Bad style:

    [A link](http://usgo.org/somewhere/overthere/)
    
  • Links to directories or domains always include the trailing slash. Failing to include this generally leads to a redirect, and hence slower loading.

    Good style:

    [A link](http://www.example.com/)
    

    Bad style:

    [A link](http://www.example.com)
    

    Good style:

    [A link](/resources/)
    

    Bad style:

    [A link](/resources)
    
  • Directory identifiers are preferred, especially instead of specifying index.html or the like

    Good style:

    [A link](/resources/)
    

    Bad style:

    [A link](/resources/index.html)
    
  • For URIs inside our domain, avoid specifying the file extension (mostly only applicable when linking to content not managed by Drupal). Instead, let you browser and our web server figure it out. This will avoid broken links when we later switch from PNG to JPEG for example, or HTML to PHP.

    Good style:

    [A link](/resources/example)
    

    Bad style:

    [A link](/resources/example.html)
    
  • Links to email addresses must always specify the mailto: part, or they don't work correctly.

    Good style:

    [Email us](mailto:example@example.com)
    

    Bad style:

    [Email us](example@example.com)
    

    On a correctly configured computer, clicking a mailto link should open the user's Email client in order to send a message to the given email address. Like so: email us.

Reference Style Links

Use reference style links for any page that you link to more than about twice. This will prevent having to specify the same URI (and "title" attribute) many different times in one page. You can use reference style even for single links if you like, it's up to you.

Define your references either at the top of the page, or directly after the first paragraph in which they are used.

Reference identifiers should be descriptive words, similar to what the link text would be. You do not need to be as careful to make the reference identifiers super descriptive, especially if you're linking to the same thing multiple times with different link text (in which case you might want a nice short general link reference).

The reference style links such as:

[I am a reference and the link text][]

[i am a reference and the link text]: http://example.com

can save you some typing (i.e., you can omit the reference identifier if it's the same as the link text). See the markdown guide for more info.

Ordered Lists

Markdown currently does not care what numbers you use to specify ordered lists (it starts at one and goes up, regardless). Do not use this feature; always start with "1." and go up from there.

Good style:

1. Alpha
2. Beta
3. Gamma

Bad style:

1. Alpha
1. Beta
1. Gamma

Tables

Only use the Markdown table syntax for small, relatively static tables. Large ones, or ones that have relatively frequent large changes can get quite messy.