Guidelines for Web Update

How to get started: (Assuming you're editing on UNIX.)

• It's essential that users be able to read the pages, and it's a lot nicer for the MCG people if they can edit. Do umask 002 to make the default mode of new pages to be 664 with your primary group, i.e. maint. If there's a question about what the mode is, do ls -l and fix as necessary: chgrp maint Page.shtml; chmod 664 Page.shtml

• The old directory is /usr/www/htdocs/computing, and the new one is /usr/www/htdocs/computing-new; let's call these $old and $new. Identify the page you want to work on; let's call it Page.shtml. When you begin there should be a symlink $new/Page.shtml which points to ../computing/Page.shtml. First remove this symlink and copy the referent page into $new except change the extension to .shtml. If the template ends in .shtml, so must the copy; this is how Apache knows to include the header.

• On a relatively clean page, working on the copy, remove the old header and footer information. Use the editor's insert feature to prepend ../templates/template.shtml. Merge information; mainly this means:

  • Set the page title (2 places) in the template and get rid of the original page title. Move a byline, if present, to just after the template's title. (Do we want / not want bylines? We decided to not have them; but put the author's name and initial version in the revision history.)
  • Move the footer template to the end of the document. Remove duplicate tags, e.g. </body>.
  • There is a specially styled <P> tag for the first paragraph; remove the original <P> tag and let the body text be introduced by the template's tag.
  • It would be nice to have a revision history. See the end of this document for an example.

• On a heavily Microsofted page, it helps to begin by using the editor's search and replace function to remove all span tags. In vi you would do (after hitting colon to get out of visual mode):

  %s/</?span[^>]*>//gi

  In detail: % selects the whole document; substitute; < followed by an optional slash, the word span, and anything up to the immediately next >, replace with a null string, globally, case insensitive.

  Then, remove the massive header down to the body tag. That will get rid of most of the crap, but there is plenty left to remove by hand.

• Alternatively if copy and paste is going to be relevant you could copy ../templates/template.shtml to become $new/Page.shtml, then edit it and paste body content into it.

• Once you have the page as clean as you can make it, uncomment the valid HTML/CSS logo area, view the page, and click on each logo. Likely you haven't touched any CSS and it will pass the first time. As for HTML, go back and fix the complaints; the verification page has a revalidate button to save browser gyrations. The reported line numbers will have a constant offset -- I believe it's 119 lines -- from the line numbers as seen by your editor, because of the included material.

Organization suggestions:

• The home (index.shtml) page should rarely have deep links, i.e. it should point to pages in the same directory it is in. Usually.

• Many pages can be just single files as with the example of Page.shtml. If a page has graphics such as screenshots or special icons, it helps if they are in their own directory. Microsoft's style is to create the web page and supporting directory at the same level; however, I prefer to make a directory, e.g. named Page, and the main page would be called Page/index.shtml. Links to such a page would just end with Page/ (save a tree, don't write out index.shtml in full). If you decide to change the organization, remember that you will need to adjust links: outward relative links need ../ and links to supporting material need to lose the containing directory.

• If there is a coherent topic with several pages, e.g. e-mail, it makes sense to have these pages in their own directory which the home page would link to. index.shtml would then point to the individual pages. These suggestions would apply recursively in the subdirectory.

• Filenames should describe the topic. For example, a page about passwords could be called passwords.shtml. But here's a bad example: there's a page of that name which turns out to be about how to set up Basic Authentication on the web. That would have been a lot clearer if there were a web directory and the passwords.shtml document were in it.

Markup Guidelines:

• Make links as relative as possible, for better maintainability and survivability in emergencies. Omit as many common elements as possible between the referrer and the target. For example, in the page http://www.math.ucla.edu/computing/email/index.shtml:

  • http://www.math.ucla.edu/computing/email/outlook.shtml -- Worst, repeats every element.
  • outlook.shtml -- That's all you need to write.
  • ../printing/index.shtml -- A relative path to a neighboring directory.
  • ../printing/ -- Better to omit index.shtml; let Apache pick the index. It saves a step if you include the slash.
  • /people/staff/ -- A reference within the same site to a separate page tree should start at the top level but omit the protocol and site name.
  • http://www.pic.ucla.edu/piclab/ -- A link to an unrelated site may be a complete URL.

• All dimensions must be relative, not in pixels, so the object will automatically be scaled to fit the user's screen and font. Give them in percent (in quotes) or in em (the nominal line height), e.g. 2em. In particular:

  • every image needs an explicit width because the default is the image's native size in pixels.
  • HTML editors tend to set table dimensions in pixels. Specify the width of a TABLE tag explicitly, generally as 100% (of the page width, in quotes). Often the HTML editor will do this for you if you mark some checkbox.
  • Similarly, COL tags need to be dimensioned in percent (of the table width), not in pixels.

• The web police (HTML validator) will insist that every image must have ALT text and every table must have a SUMMARY text. Think of a blind person seeing the image; give him a very short text telling what we're seeing.

For more guidance:Several years ago I wrote up a document on web standards which never got management buy-in. It has more rules (that are embodied in the included header and style sheet so you probably will not need to actually do anything about them), and it has rationales as well. Here are the links:

• Web Policy Document
• How well people follow these guidelines

Revision history:
2009-03-12 First published (jimc)