Coding and File Management Guidelines

By Duane Taylor, International Institute for Sustainable Development (IISD)
May 2001

Coding

One of the biggest problems with Web pages is that they do not work in all browsers. With many sustainable development groups having target audiences in areas where Internet connectivity and computers are not optimal, this is of great concern. All code used should meet international standards (see World Wide Web Consortium (W3C)). This is important to consider when considering in the use of HTML, CSS, Javascript, XML, XHTML, DHTML, etc.

If Web page editors, such as FrontPage and Dreamweaver, are to be used they should be chosen carefully. Many editors are simple to use, but create very messy code that my not comply with W3C standards. The editors should have a validation feature to ensure standard compliance.

One way to keep the code clean is to implement the use of cascading style sheets (CSS). Not only is this a great tool to maintain the visual standard of each page of a Web site, it also allows attributes of HTML tags to be stated once throughout an entire Web site. CSS is becoming a widely used tool and is evolving to become more adaptable. The user must be aware that some browsers may have trouble reading CSS files so there has to be a trade off between site consistency and isolating a very small minority of users.

The code should also be documented in a standard format set up at the beginning. On pages where the code is particularly long, it is necessary to document properly. This will allow the Webmaster to locate specific areas and fix possible problems more easily. It also allows for smoother transitions when staffs change.

File management

Conventions should also be set up to give a standard system to the names and place of all files. As with coding style guides, file management guides will help in saving time and frustration when a new employee has to work on the site. This is very important for CSOs because of the naturally high turnover rate of employees dealing with Web management and content. There should be strict guidelines as to what a file can be called or where it can be placed and all employees that contribute to the Web should know them.

The file management should have a logical pattern that reflects the information that is presented. If a site is broken into several modules a logical way to breakdown the file structure may be to have a folder for each module. How a group decides to name folder and sub folders is not the issue, making sure a group agrees upon a structure and what files belong where is the important thing. Naming conventions should also follow a logical pattern that a group decides upon. For instance, the Spanish and French files for IISD's Web site all have the prefix "es_" for Spanish and "fr_" for french.

Images are a good example. If a site is fairly large it is recommended that there is a folder dedicated to just images instead of having images placed in the main directory. The folder could be called, "images" for simplicity. The image names should also follow a guideline.

Another aspect to consider when naming and constructing files is the actual URL address that the user will see. The names should be kept short, simple and reflect the content. If your URL for a section on economic research is "http://iisd.org/economics_are_fun/folder1/index.html" instead of something like "http://iisd.org/economics/research" it is obvious which makes more sense. The latter will also allow a user to assume sections and type in a URL for a section they are looking for and possibly find it.

Once the organization has decided on a guideline that can easily be followed, the question to be asked is, "if I created a page about 'x' would I instantly know what the file name would be and where it would be placed?"

Example

In late 2000, the Panos Institute in Dakar (http://www.panos.sn/) promoted an intern to the position of Webmaster after their current one left for other pursuits. After quickly learning how to deal with most of the work, the intern had to make some minor changes on the home page. She proceeded to make the changes and saved the file as "index.html". Unfortunately the proper ending was "*.htm".

This simple mistake, compounded with the fact that they did not have a test area before things went live on the Internet, caused Panos' main page to be inaccessible for three days. The site became unusable to many users who would have normally entered from the homepage.