Submission Style Guide: Code

This document outlines the acceptable tags for use in posting articles. Please use simple, clear XHTML 1.0 Strict markup.

Use Semantic HTML

<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. (The title of your article will be rendered as <h1>.) Please use headings 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.

Italic and Bold

Please use the <em></em> pair to emphasise text, and the <strong></strong> pair to strongly emphasise. Avoid using <i>, or <b>, and avoid underlining text. Wrap short quotes in <q></q>, and longer quotes in <blockquote></blockquote>.

This is italic text This is bold text This is a short quote.

This is a blockquote.

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, Definition Lists)

The <ol>, <ul>, and <dl> tags will all work.

• bullet 1
• bullet 2
• bullet 3

1. ordered list item 1
2. ordered list item 2
3. ordered list item 3

definition title

This is a definition list. This is the definition section of the definition list.

Forms and Form Elements

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

Tables

Please use <thead>, <tbody>, and <tfoot> to delineate the header, body, and footer of the table. Please use for header cells.

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.

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, for example, changing all your < and > characters into > and < entities. 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.

This is how a block of code will appear on the site.  Long lines of text will result in a scrollbar that doesn't mess up the layout.
Short lines will
be rendered thusly

Inline Code

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

This is a sample of inline code.

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.

1. 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.
2. 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.
3. 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.
4. 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.