This is the third and final part of the series. If you haven’t read the other parts, you can find them here and here. The following is a heavily edited version of an internal document that I wrote a number of years ago to try to standardize internal web development.

Rule 7: Javascript

• (This was addressed to designers who were copy/pasting chunks of javascript code that they didn’t understand into files, and causing additional work for the development team): jQuery is great. We like jQuery. Please don’t go overboard though. You’re better off letting the programmers know what something is supposed to do.
• Most javascript code should be in separate files (i.e. not inside your html). If you know how, please put code into appropriately named functions.
• There only needs to be one “bootstrap” function to start things. This should probably appear at the bottom of your layout. If you don’t know what this means, we will be happy to show you.
• Please avoid using inline javascript on tags if possible. There’s a simple way to attach a function (i.e. onclick) to a tag inside your script files – and that will allow you to document things properly and have nice clean maintainable js code. If you don’t know how, just document what you’re trying to accomplish and let the programmers do it. Your html layout should contain html markup and content only. CSS file are for CSS, and JS files are for Javascript.

Rule 8: Lists and Tables

Please be sensible and pragmatic about the usage of both of the above (i.e. lists and tables).

It is ok to use a table to display tabular content. In fact, if you try to do this using lists, you will probably be creating extra work for yourself (and the unlucky people to have to maintain your work later).

It is not ok to use tables for large scale positioning of layouts. Please use nested “divs” for that.

Rule 9: Images

All images must have an alt tag. Period. The exception would be images used as backgrounds of divs, in the context of your layout.

All images must have sizing. Its better if it is in your css, but this is one exception to inline rules.

If the image has text on it, or if it is intended to be clickable, please use an image tag instead of putting it as the background of a div (and then sticking an “a” tag around the div!). The image link – along with its alt text and other contextual stuff – will work far, far better in a mobile device or a reader for the visually impaired. In fact, even if the image is part of your layout, consider using an <img> tag instead of a backgrounder, if there is any rendered text in it.

Rule 10: Links

All links should have titles. This is a big part of making websites compatible with devices for the visually impaired – and also for many types of mobile browsers. Be sensible with the text in the link title – describe in a few short words what the link will lead somebody to if they click on it.

Rule 11: Navigation

Navigation bars must be implemented with text links. No images – its impossible to maintain a nav bar where the items are images containing text. There are various clean ways of using nice fonts for your navigation purely through html.

Nav bars should use unordered links and css for markup. If you need fancy, use something standard like Suckerfish.

(The following was addressed to a particular designer who wasn’t careful about nesting) Please do not put any markup inside the <ul> tags that isn’t inside an <li> tag. We frequently encounter divs that are randomly floating inside the list, but aren’t inside of an <li>. Remember that the navigation will probably be maintained by a CMS system. That means it needs to be extremely predictable, and possible to generate from code.

Updates

In the years since I wrote the original document, a number of things have changed (i.e. web frameworks sometimes dictate formatting, the rise of css3), and I’ve also learned many things (accessibility) that I had only a passing familiarity with at the time. I’ve made edits to the content to some extent, but decided not to add too much in, due primarily to lack of time (and some social pressure, as several friends have been bugging me for the full document, which I prefer not to release in unedited form!). As a result this is far, far from an exhaustive (or entirely accurate) list. Please take it in the context in which it was written – an attempt to set some standards for internal developers, in order to ensure some level of consistency. At some point, time permitting, I may come back to this topic in more detail.