Web Writing Guide for the CS Department

Highlights of this document:

This document aims at defining a style of writing instructional material on the web for CS Department. Examples for these materials include online lab materials and online class materials, among others. The purpose for defining a style is to give our web pages a consistent look. This will in turn make it easy for students to find their way around numerous online materials in the CS Department. This document can be regarded as a "meta-template", as it is a template about template, and can be regarded as a sample of the instructional materials you are about to write for the CS Department.

This document should be read and its instructions adhered to when creating any kind of online document for the Computer Science Department. If you wish to make changes or include additions, please contact the webmaster at webmaster@cs.uregina.ca.

The highlights of this document include:
  1. General layout
  2. Use of stylesheet
  3. Font etc.
  4. Comments about comments
  5. Locations of images used in this document
  6. End notes

1. General Layout

We suggest that you divide your online document into the following four sections: the header section, the preview section, the main section and the footer section.


1.1 The Header Section

The Header Section for a Lab document includes a title, and a link to the lab stylesheet. The Header Section for a Department document includes a title, and a link to a pre-defined header. Note: The CSHeader contains the closing HEAD tag (</HEAD>) and the opening BODY tag (<BODY>), so if you wish to include more content in the HEAD section, you must place it before the CSHeader include.

Here is the HTML code for a Department document:

<HEAD>
<TITLE>TITLE</TITLE>
<!--#include virtual="/include/CSHeader.html" -->

Here is the HTML code for a Lab document:
<HEAD>
   <TITLE>TITLE</TITLE>
   <link rel="stylesheet" type="text/css" 
   href="http://www.cs.uregina.ca/Style/lab.css">
</HEAD>

1.2 The Preview Section

The preview section, as the name suggests, gives the reader a preview of the content of the current document. This is especially useful for online class or lab material writings.

This section should include a very brief overview remark, followed by an ordered or unordered list of the topics covered in your document. To make it easier for your reader to get to specific topics of your document, it is suggested that you make this list of topics "in-document" links. That is, from this section, if the reader click on a certain topic, s/he should be taken to the part of the current document where this topic is discussed. For example, if you go to the top of this web page and click on "The Preview Section" in the "Highlights of this Document " section. You will be taken back to this section again.

1.3 The Main Section

This is where the most important part of your document lies. The layout of this part depends on the kind of document you are writing. It is suggested, though, that you break the whole document into smaller sections and make the title for each section obvious for the reader to follow.

1.4 The Footer Section

The Footer Section should contain various informational items. Depending on whether you are writing a Department document or Lab document, your footer will be slightly different. The pre-defined footer used for the Department pages contains the last modified date, the email address of the webmaster, as well as various links.

Go to the very bottom of this page and see how the footer looks like. The following is the HTML code that generated the footer for this page (and that should be used for Department documents). Note: The CSFooter contains the closing BODY tag (</BODY>), so make sure that you do not include one in your code.


<!--#include virtual="/include/CSFooter.html" -->

If you are writing Lab documents, you should use this template as your footer:

<BR><BR>
<HR>
<CENTER>

<TABLE BORDER=3 WIDTH="70%">
  <TR BGCOLOR="CCCCCC">
    <TD><CENTER>
      <A HREF="http://www.cs.uregina.ca/">CS Dept Home Page
      </A></CENTER>
    </TD>
    <TD><CENTER>
      <A HREF="http://www.cs.uregina.ca/Academic/teaching/">
      CS Dept Class Files</A></CENTER>
    </TD>
    <TD><CENTER>
      <A HREF="ADDRESS OF THE LAB WEBSITE">
      CSXXX Files</A></CENTER>
    </TD>
  </TR>
</TABLE>
<BR><BR>

This page last modified:
<!--#flastmod file="index.html"-->
<BR><BR>

<IMG SRC="http://www.cs.uregina.ca/Style/gifs/copybtn.gif" 
             HEIGHT="30" WIDTH="30" BORDER="0" ALIGN="CENTER">
<B><I>
Copyright: Department of Computer Science, University of Regina.
</I></B>

Note: You need to replace "index.html" with the name of your document and substitute in your name where Your Name appears.

2. Use of Stylesheet

For the same reason of preserving a consistent look of the CS Department web pages, we promote the use of cascading stylesheets. For those of you who are not familiar with this term, a cascading style sheet is an extension to the HTML language. It is simply a text file, with the .css suffix, which defines the attributes of the HTML tags used in the document that uses a cascading style sheet. All code examples in Lab documents (and in this webpage) have a border. This is achieved by using a stylesheet. Let's see how this is done in detail. But before that, we need to know how to let the browser know that you are actually using a stylesheet in your HTML document. (All code samples in this section use the Lab style).

To use a stylesheet, you need to add the following statement in your HTML document.

    <link rel=stylesheet href = /path/to/stylesheet.css 
type = "text/css">

where /path/to/stylesheet.css is the path to the stylesheet file. When writing an online document for the CS Department, you need to replace the above path with /Style/lab.css, the path to the stylesheet you are going to use.

(Note: There are more than one way of including a stylesheet file in a HTML document. It is beyond the scope of this document to discuss all of them.)

Take the following HTML code:

<PRE>
  <CENTER>
  <IMG SRC = "table1.gif"
	  HEIGHT = "77" WIDTH = "92" BORDER = "0"> 
          <H1> Sample Title </H1>
  </CENTER>
</PRE>

As you can see, there seems to be no trick played here, because all we used are a pair of <PRE></PRE> tags. (Actually, we used the same tags to generate the above text.) The trick is in the stylesheet file used for this document. In the file lab.css, we defined some attributes of the <PRE></PRE> tags. Here is the portion of the lab.css which defines the <PRE></PRE> tags that generate the double navy border:

Pre.Xmp
        {
        background-color: #FFFFFF;
        font-family:      Courier,fixed,serif;
        color:            blue;
        width:            270px;
        white-space:      pre;
        font-size:        10pt;
        border:           double navy;
        margin-left:      1em;
        margin-right:     1em;
        }

This block of code defines the background color and border of the text surrounded by the <PRE></PRE> tags, and some other attributes. Therefore, whenever <PRE></PRE> are used to quote programming code, the code will be represented in exactly the same manner throughout this document. This makes maintaining and updating a web site very easy. For example, if later on you decide to use a different color for the border, all you do is to change the colorattribute for the PRE section in the lab.css file.

We ask that you use the lab.css stylesheet file in your web documents. This file is by no means the final version of the ideal stylesheet, but as is mentioned above, we can always change it later on and the appearances of the web documents that you have created will change accordingly. It's almost painless.

Since we are going to use the stylesheet, which has already defined the attributes of many HTML tags, you DO NOT need to redefine these attributes in your HTML files. For example, the background of all the web documents is defined as #FFFFFF (white) in the lab.css file, you do not need to specify the background attribute in the <body> tag. Also, do not specify the color attribute, or any other attributes of the <H#> tags, (where # stands for numbers from 1 to 7) because they have already been defined in the stylesheet and redefining them would beat the purpose of using a stylesheet.

3. Font etc.

As is defined in the stylesheet (http://www.cs.uregina.ca/Style/lab.css ), we use the Arial family of fonts for our online documents. However, this is not carved on stone; you can choose to use other fonts, but make sure they are easy to read.

The default font size is 12 points. However, there are exceptions. For example, the main title and section headings should use larger fonts. Again, these are defined in the stylesheet. We suggest that you use <H1> for the main title (In this document, it is "A Guide to Online Writing for CS Department") and use a lower-level heading for each subsequent lower-level titles (For example, we used <H2> for the section titles in this document). Remember, the attributes of the <H#> headings have been defined in the stylesheet and therefore you do not need to redefine them.

There are also exceptions to the font style you use in your online document. These exceptions mainly apply to the quoting of programming source code. There are two situations concerning the quoting of source code: 1) the source code is long enough to warrant a separate paragraph and 2) the source code does not need to be placed in a separate paragraph (An example of latter case is variables of a programming language).

For 1), we suggest that you use the <PRE></PRE> tags, because we have defined the attributes of this pair of HTML tags in the stylesheet so that any text put in between will be placed in a red rectangle with light blue background. Click HERE for an example from this document.

For 2), we suggest that you use the <VAR></VAR> tags. You can find examples of this in various places of this document.

4. Comments about comments

Although there are controversies concerning whether HTML should be regarded as a programming language, we do require that you use documentations in your code, as you generally do in any traditional programming languages. You use comments for your HTML code for the same reason you do this to your C or Java code. A minimum requirement for commenting your HTML code is that you use comment to mark the beginning of each logical section of your document.

For C programming language, you put your comment between /* and */; similarly, for HTML, you put your comments between <!- - and - ->. Comments will not get displayed in the browser, because they are there for the web authors, not viewers, to see.

5. Locations of images used in this document

For the purpose of clearer illustration, we encourage the use of images in your online document. Remember, however, that more images in an HTML document means longer loading time, which can make your viewers frustrated.

6. End notes

Click HERE for an example online lab material.

We do not intend to use the above guidelines to limit your creativity. Besides, this is only the first draft of the web template that we are working on. Therefore, your criticism and comments are very welcome.


To Top of Page