Submission Style Guide: Code

Adrian Roselli

Member info | Full bio

User since: December 13, 1998

Last login: March 11, 2006

Articles written: 47

Article Info

Posted on April 16, 2001 in FAQ by Adrian Roselli (aardvark)

Rated 4.33 (Ratings: 27) (Add your rating)

Want more?

More articles in FAQ
More articles by aardvark

This document outlines the acceptable tags for use in posting articles. Please note that while you may use other tags, our editors (or our CMS) will most likely remove them before posting. This site is coded to xHTML 1.0 Transitional, so please only use elements and attributes from that specification. In particular, please remember:

All tags must be properly nested
<img> and <br> tags need to be self closing: <img src="foo.gif" alt="bar" /> and <br />
All markup must be in lower case, and all attributes quoted

<h#> Tags and Their Use

The <h#> tags should be used for section headings. Using <h1> is forbidden since that is the top-most title of every page. Please use them in order; don't skip to <h3> without first using <h2>. For your settings, the <h#> tags will render as:

This is the <h2> tag

This is the <h3> tag

This is the <h4> tag

This is the <h5> tag

This is the <h6> tag

Paragraphs

Please wrap each paragraph within a <p></p> pair.

Styling Text

Bold

Please use the <strong></strong> pair to strongly emphasise. This is preferred to <b> since it describes structure instead of style.

This is bold text

Italic

Please use the <em></em> pair to emphasise text. This is preferred to <i> since it describes structure instead of style.

This is italic text

Underline

Please do not use the <u></u> pair to underline text. Not only is it deprecated, but it may confuse users about whether or not it is a link. If you think something should be underlined, it would probably be more correct to make it bold or italic.

Color

Do not apply any color to any text via CSS or the <font> tag. The CSS for the site allows any user to customize the colors and fonts, and setting colors would override those settings, possibly hiding your text.

The <font> Tag

The <font> tag is not allowed, if you use it we will remove it. All font properties for the site are defined via the CSS and customizable by each user. All markup must be structural; the <font> tag does not denote structure. Also, the <font> tag is deprecated.

Script and Code Samples

If you're using block-level code samples (see below), please don't forget to escape all your entities. This means, in particular, changing all your > and < characters into &gt; and &lt; entities (respectively) as well as & to &amp; and " to &quote;. You can get a complete list of the accepted character entities from section 24.2 Character entity references for ISO 8859-1 characters of the HTML 4.01 specification at the W3C site. There is also a character entity chart right here on the evolt.org site: A Simple Character Entity Chart

Code Blocks

Blocks of code/script/markup should be placed between <pre></pre> tags. Since <pre> is a block level element, it will be rendered as its own paragraph.

You may also post block level PHP code between <?php ?> tags for pretty syntax colour coding:

	<?php
   /**
    * procLogin - Processes the user submitted login form, if errors
    * are found, the user is redirected to correct the information,
    * if not, the user is effectively logged in to the system.
    */
   function procLogin(){
      global $session, $form;
      /* Login attempt */
      $retval = $session->login($_POST['user'], $_POST['pass'], isset($_POST['remember']));
      
      /* Login successful */
      if($retval){
         header("Location: ".$session->referrer);
      }
      /* Login failed */
      else{
         $_SESSION['value_array'] = $_POST;
         $_SESSION['error_array'] = $form->getErrorArray();
         header("Location: ".$session->referrer);
      }
   }
?>
	
	
	

Inline Code

Code/script/markup snippets within a paragraph should be wrapped within <code> tags. This will escape all your entities for you.

This is a sample of inline code.

Linking

Whenever possible, please try to add a 'title' attribute to your <a> tags. So a tag may appear like this:

<a href="foo.html" title="Latest report on water fowl mortality rates">.

Off-Site Links

Please add a 'target' attribute to your links to open a new window so readers of your article on evolt.org don't lose their place. Please use "_blank" so all new links open in one window, since the use of "_new" opens links in a new window for each link. To expand on the above example:

<a href="http://foo.com/foo.html" title="Latest report on water fowl mortality rates" target="_blank">.

Miscellaneous Tags

Abbreviations

Whenever you use abbreviations in articles, please keep in mind that not everyone knows all abbreviations out there. To allow users to see what an abbreviation means, you can wrap it in the <abbr> tag and add a title attribute with the full name of the abbreviated item. For example:

The W3C is an example of this in action. The abbreviation in the previous sentence uses the <abbr> tag.

Acronyms

Whenever you use acronyms in articles, please keep in mind that not everyone knows all the acronyms out there, either. To allow users to see what an acronym means, you can wrap it in the <acronym> tag and add a title attribute with the full name of the acronym. For example:

WYSIWYG is an example of this in action. The acronym in the previous sentence uses the <acronym> tag.

Horizontal Rules

The <hr> tag will render as:

Bullet Lists (Ordered, Unordered, Dictionary Lists)

The <ol>, <ul>, and <dl> tags will all work. No special formatting is applied via the CSS. You can see examples of lists below.

Forms and Form Elements

Please do not use any <form> tags or elements.

Tables

You may use all the normal attributes for your tables. This includes cellpadding, cellspacing, border, align, and valign. Please do not color any table cells or content as it may conflict with user-defined styles. Please use <thead>, <tbody>, and <tfoot> to delineate the header, body, and footer of the table. Please use <th> for header cells. A sample table:

Header1 (<th>)	Header2 (<th>)	Header3 (<th>)
Cell1A and 1B	Cell2A	Cell3A
Cell1A and 1B	Cell2B	Cell3B
Cell1C	Cell2C and 3C

Data Tables

Just in case you have a table with tabular data that you want to display with gridlines, we've created a class to do just that. Simply add class="data" to the table tag. You will also need to set "cellspacing" to 0. The minimum code to render a table this way is: <table cellspacing="0" class="data">. An example table is below.

Header1 (<th>)	Header2 (<th>)	Header3 (<th>)
Cell1A and 1B	Cell2A	Cell3A
Cell1A and 1B	Cell2B	Cell3B
Cell1C	Cell2C and 3C

JavaScript

Please do not use JavaScript (or VBScript, or ECMAScript) in articles. If it is necessary for an article, we may leave it, and most likely will edit it. Otherwise, all submissions with any client-side scripting will have it removed.

Allowed Tags

Following is the list of accepted tags, most of which have been covered above.

<br />

<img>

Writing Style

Research has shown that the writing on a web site has a significant impact on the usability (and therefore effectiveness) of a site - up to 125% improvement. The following are outline guidelines, which will significantly improve the impact of our copy.

Be succinct - no more than 50% of equivalent wordage in print
BECAUSE
Reading from screens is substantially slower than from paper. Users intensely dislike reading long texts.
1. Be scannable - structure articles with 2 or 3 headlines (nested if necessary).
2. Use meaningful rather than teaser headlines and subheads (reading a headline should tell users what the section's about).
3. Use text weight and colour to add highlighting and emphasis.
4. Use bulleted lists.
  BECAUSE
  1. Users do not read copy in full (at least not on 1st reading), they scan. Headlines and page titles are often viewed out of context.
  2. Users are adept at disregarding everything that does not look like a clear headline and do not waste their time on links which may be a waste of time.
1. Structure long documents. Content should not be arbitrarily cut up into page 1, page 2 etc. Each page should encapsulate a discrete topic. Each page should be written as an inverse pyramid, with a clear summary of the page at the start.
2. Secondary and background information should always be available on separate pages accessed from a link.
3. Printable versions should be on a single page.
  BECAUSE
  While users dislike long documents, they particularly dislike having to download several pages to cover one topic. They do like choice over which subtopics to read.
Use cool, objective language to build credibility.
BECAUSE
Users detest marketing copy - a promotional style with boastful claims. Users are busy, they want the facts, and tend to believe content which gives it to them without embellishment.
1. Linked text should describe where the links lead, not give ‘click here’ instructions. An appropriate way to consider linked text is that it should represent the headline of the content users will arrive at.
2. Use link titles to give additional explanation if warranted.
  BECAUSE
  Users do not follow bad links, and links can be presented out of context by certain browsers and search engines. ‘Click here’ instructions also break up the flow of text and make it more difficult to read.

Bibliography: http://www.useit.com/papers/webwriting/

A founder of evolt.org, Adrian Roselli (aardvark) is Vice President of Interactive Media at Algonquin Studios, located in Buffalo, New York.

Adrian has years of experience in graphic design, web design and multimedia design, as well as extensive experience in internet commerce and interface design and usability. He has been developing for the World Wide Web since its inception, and working the design field since 1993. Adrian is a founding member, board member, and writer to evolt.org. In addition, Adrian is also an exiting board member of Brainstorm, the Buffalo American Advertising Federation affiliate, and sits on the Digital Media Advisory Committee for a local SUNY college.

You can see his personal portfolio at http://roselli.org/.

Adrian authored the usability case study for evolt.org in Usability: The Site Speaks for Itself, published by glasshaus. He has written three chapters for the book Professional Web Graphics for Non Designers, also published by glasshaus. Adrian also managed to get a couple chapters written (and published) for The Web Professional's Handbook before glasshaus went under. They were really quite good. You should have bought more of the books.

While you're reading, a friend of mine has just launched her site, and you should take a look. Kristen Kos, a lovely and talented actress, now has her own site with her acting resume and some new head shots.

7 comments on this article. Log in to add your comment | Rate this article:

Does this style guide apply to comments?

Submitted by lisrael on September 8, 2002 - 19:33.

Great style guide. But it's not clear to what extent this style guide applies to comments. The fact that the comment form links here suggests that it does, at least in part. But on the other hand, the article begins by saying:

This document outlines the acceptable tags for use in posting articles.

(Emphasis added.) It would be nice if someone at evolt would make it clear which portions of this style guide we are supposed to use when posting comments, or correct the opening sentence of this article if it is intended to apply to comments.

Yes, this applies to comments.

Submitted by aardvark on November 22, 2002 - 11:36.

This style guide does apply to comments. In fact, we've linked to it right above the text area used to write comments, so ideally members would see it:

Share your opinion below. You must use HTML in your comments if you want any formatting, such as paragraphs, but please check out our style guide to see what HTML we'll allow.

Nitpicks

Submitted by jim.dabell on August 13, 2003 - 10:00.

Tags... tags... tags...

Nitpick: You are referring to elements where you use the word "tags" in most places.

Please use the <strong></strong> pair to make text bold. This is preferred to <b> since it describes structure instead of style.

This is incorrect. It should read "Please use <strong> elements to strongly emphasise text. If all you want to do is make text bold, you should use a <b> element. The same applies to the <em> element type - it's for emphasis, not italics. You are confusing structure and style as much as somebody who uses <i> for emphasis.

Blocks of code/script/markup should be placed between <pre></pre> tags.

Shouldn't that be <pre><code></code></pre>?

Please add a 'target' attribute to your links to open a new window so readers of your article on evolt.org don't lose their place.

This is very annoying. I think we can be trusted to be able to open links in new windows if we want. Furthermore, the target attribute is deprecated - what about <a rel="external"... and a bit of Javascript to open them in a new window instead (if you must)?

nitpicks? nah...

Submitted by aardvark on August 13, 2003 - 12:54.

To answer in order (which is why it will read weird if you don't read the previous post)...

I chose to use the word tag over element simply because I felt more readers would know the word. If you watch on the list, when people refer to those letters in brackets, they usually say tag over element.

My statement in the article is just not accurate. <strong> should be used to emphasize text because it imparts semantic meaning, not structural meaning. As for people making text bold for the sake of bold (or italic), we prefer to not allow it. We've found it's often a misuse of the tag to use <i> or <b>, so we'd rather people not use it and we can be the final arbiters of what's appropriate.

No, we felt nesting a <code> within a <pre> was redundant and didn't offer any extra value. For the scope of this site, we view <pre> as the block-level cousin of <code>, and so use them accordingly.

Actually, according to the HTML 4.01 Transitional specification, which is what the site is coded to, the target attribute is quite legal:
http://www.w3.org/TR/html401/index/attributes.html

As for opening links in new windows, this is something we have debated for some time. The next version of the site will likely not allow this as it might go to XHTML. And as for using script to do it, we've tried very hard to make this site work without script, and we'd really rather not have embedded script in the submissions.

Please keep in mind that these code standards were written nearly two and a half years ago for a site released even before that, before the names in the industry (Zeldman, etc.) started converting their sites to all-valid mark-up and it became the cool thing to do. Clearly there has been time for us to change our opinions on code use, but to change it every few months would be a disservice to our authors and to when we actually do convert the site to another mark-up standard. If you have further feedback, consider joining into the discussion for the next evolt.org version. We are all volunteers, so any help can be good.

Article Categories

evolt.org community

Submit

Highest rated articles

Recent comments