Notes on XML Module Descriptions

Contents

Changing your syllabus & module description

  • Go to the existing syllabus page. This will be found at http://www.cs.bham.ac.uk/resources/modules/YYYY/XXXXX.html, where YYYY is the academic session (e.g. 2007 for 2007/08) and XXXXX is the Banner code. Alternatively, follow the links from http://www.cs.bham.ac.uk/resources/modules/. Make sure you have the correct year.
  • Download the XML source file via the link at the very bottom of the syllabus page. If you're using Internet Explorer, it displays XML quite nicely, checking its syntax. Please do not use a copy of the XML source file you may have in your own user area -- since your old version may have been changed without your being aware of this.
  • Edit the file to produce the content you want. Any text editor will do. Note that changes which affect the module description may require Teaching Committee approval (see the XML elements listed below); you are free to make any other changes.
  • Return the edited file to Laura Ewers, either as an e-mail attachment or just as text in an e-mail. She will check it and generate the module description and syllabus pages.

Creating a new XML module description

  • There's a template which can be downloaded at /bham/htdocs/www/resources/modules/template.xml. (It won't display correctly in Internet Explorer because it isn't in the correct directory to find the path to the DTD.)
  • Edit the file to produce the content you want. Any text editor will do.
  • Return the edited file to me, either as an e-mail attachment or just as text in an e-mail. I'll check it and generate the module description and syllabus pages for approval by Teaching Committee, etc.

XML format

For those not familiar with XML, please note the following:

  • XML is case-sensitive unlike HTML. <A> is not the same as <a>.
  • Although XML allows the user to define new elements (tags), you cannot because the XML used in module descriptions will be 'validated', i.e. checked against a pre-specified document type definition (DTD). You can only use the elements defined in http://www.cs.bham.ac.uk/modules/MD.dtd and then only in the right places!
  • Unlike HTML, all XML elements must be properly terminated. Every <X> tag must be terminated by an </X> tag. If a tag contains no content, then <X/> is equivalent to <X></X>.
  • XML must be properly nested. In HTML, many browsers allow e.g. <I>this <B>is</I> not correct XML</B>, generating 'this is not correct XML'. XML does not allow this. (Subject to the DTD allowing I and B elements and their nesting, you would have to write e.g. <I>this <B>is</B></I> <B>not correct XML</B>.)
  • White space is generally ignored when processing XML, so you can indent and align as you choose.
  • The only 'literal entities' allowed in XML (at least as used here) are &amp; &lt; and &gt;. The last two shouldn't be needed. &amp; must be used in place of &. All other non-ASCII characters must be represented by numerical entities using the format &#ddd; where ddd is a decimal number. For example, í must be represented as &#237;. See /~pxc/web/isolatin1.html for a table of values.

Elements in the XML module description

Status of elements

The status of each element is given in brackets.

  • Fixed -- cannot be changed by the module provider.
  • Freely variable -- the module provider is free to change these at any time.
  • TC approval -- significant changes in the values of these elements should be put to Teaching Committee for approval, ideally before the Easter before the start of the academic year in which the change is to be made.

Including elements from other module descriptions

For each of the elements Aims to Links below, you can replace its entire content with an Include element. This has only the code attribute. For example:

<Aims>
  <Include code="11223"/>
</Aims>

This will include all the aims in the module description for 06 11223 in the generated HTML. You cannot include part of an element (e.g. you cannot include only the first 3 aims).

code="xxxxx" [Fixed]

The value of the code attribute must be either the last 5 digits of the Banner code (currently unique) or a temporary School alias beginning with 'N'.

academic-yr="yyyy" [Fixed]

It should have a value like 2007. It refers to the academic year in which the module description is valid even if the module has not yet been taught.

LastUpdate [Freely variable]

Put here the date at which you make your changes. Use the format DD MMM YYYY, e.g. 12 Mar 2007.

Aims [Freely variable]

You may supply any number of aims, but 3-8 is recommended. The aims should follow on grammatically from "The aims of this module are to:", i.e. they should begin with a verb. Each aim should be a single sentence. Start each aim with a lower-case letter and don't include any punctuation at the end.

Aims are not included in the module description, so you can change them at any time.

Aims are what you, the module provider, intend to do in the module. Typical verbs are "present", "demonstrate", "introduce", "illustrate", "show", "facilitate". Here's one example:

<Aims>
  <Aim>present the basic ideas of the pure functional programming
    language Haskell</Aim>
  <Aim>demonstrate the main elements of good programming style</Aim>
  <Aim>illustrate some of the uses and applications of Haskell</Aim>
</Aims>

Outcomes [TC approval]

You may supply any number of outcomes, but 5-10 are recommended. The outcomes should follow on grammatically from "At the end of this module, the student should be able to:", i.e. they should begin with a verb. Each outcome should be a single sentence. Start each outcome with a lower-case letter and don't include any punctuation at the end.

Learning outcomes are what the student should be able to do. Typical verbs are "identify", "explain", "use", "analyse", "solve", "suggest", "employ". Don't use "know" (since "the student should be able to know" isn't acceptable English). I personally try to avoid "understand", since it seems a bit passive (a fudge is to replace it by "demonstrate an understanding of"). Ask yourself how you would know that the student understood. If the answer is that the student could explain, then use "explain", and so on.

You also need to state how the outcome is assessed. If the only form of assessment is by examination, then the answer is obvious. Otherwise state for each outcome how it is assessed. The School currently tends to use only one of four forms for the Assessed element:

  <Assessed>Examination</Assessed>
  <Assessed>Continuous assessment</Assessed>
  <Assessed>Examination, Continuous assessment</Assessed>
  <Assessed>Continuous assessment, Examination</Assessed>

If more details are given (e.g. "Class test" instead of "Continuous assessment"), the Academic Office needs to be told every time the form of the assessment changes. See also the Assessment subheading below.

Opinions differ on whether to define outcomes which can't be assessed within the scope of the module. If it's really appropriate I probably would, but this is a hostage for future critics, so do it with care!

Here's an example:

<Outcomes>
  <Outcome>explain some of the main knowledge representation formalisms
    and algorithms used in AI<Assessed>Examination</Assessed>
  </Outcome>
  <Outcome>apply them to example
    problems<Assessed>Continuous assessment</Assessed>
  </Outcome>
  <Outcome>discuss their advantages and
    drawbacks<Assessed>Examination</Assessed>
  </Outcome>
  <Outcome>explain some of the relationships between the subfields of
    AI and their techniques<Assessed>Examination</Assessed>
  </Outcome>
  <Outcome>demonstrate a knowledge of search algorithms and their
    properties<Assessed>Continuous assessment, Examination</Assessed>
  </Outcome>
  <Outcome>make informed decisions about what AI techniques to consider
    in particular domains<Assessed>Examination</Assessed>
  </Outcome>
</Outcomes>

Restrictions [TC approval]

This element can be omitted (in which case the value 'None' will be generated from the XML). Existing XML files currently mostly contain:

<Restrictions>
  <P>None</P>
</Restrictions>

You can insert any number of 'paragraphs' under this element, each enclosed in <P></P>. Note that although I've deliberately chosen the same element as in HTML, the only further mark-up allowed within a P element is <Code></Code> (see Prereqs). The values of P elements should contain all necessary punctuation.

Restrictions are things like module combinations which are not allowed or limits on the numbers of students that can be admitted.

Prereqs [First P requires TC approval, rest freely variable]

This element can be omitted (in which case the value 'None' will be generated from the XML).

Prerequisites are modules in which credit must already have been gained, i.e. which were taken and passed in a previous stage (= year except for the last two years of an MEng which form a single stage). You can have any number of 'paragraphs' under this element, each enclosed in <P></P>. However, only the value of the first P element will be included in the module description supplied to Academic Office. Thus this should contain a self-contained summary. The values of P elements should contain all necessary punctuation. The only mark-up allowed within a P element is <Code></Code>, which should enclose the five digit Banner code of any prerequisite module. Don't give any other information about the module -- its name will be automatically included when the XML is expanded.

Some examples:

<Prereqs>
  <P>None.</P>
  <P>However a knowledge of C would be useful.</P>
</Prereqs>
<Prereqs>
  <P>(<Code>08744</Code> and <Code>08745</Code>) OR (<Code>08747</Code>
    and <Code>08750</Code>).</P>
  <P>Knowledge of a programming language and
    experience in programming are essential.</P>
</Prereqs>

Coreqs [First P requires TC approval, rest freely variable]

This element can be omitted (in which case the value 'None' will be generated from the XML).

Corequisites are modules which must be taken in the same stage, either before or after the given module. The format is exactly as for the Prereqs element.

Teaching [First P requires TC approval, rest freely variable]

This describes the teaching and learning methods used. You can have any number of 'paragraphs' under this element, each enclosed in <P></P>. The values of P elements should contain all necessary punctuation. However, only the value of the first P element will be included in the module description supplied to Academic Office. Thus this should contain a self-contained summary. A typical example might be 'x hrs per week of formal lectures plus y hrs of laboratory work'. Subsequent 'paragraphs' can expand on the summary.

Example:

<Teaching>
  <P>2 hrs/week of lectures plus 5 hrs total of exercise classes.</P>
  <P>Extensive use is made of online material.</P>
</Teaching>

ContactHrs [Fixed by <Teaching>]

Calculate this as the total number of hours the student has contact with a member of academic staff, teaching assistant or demonstrator. Don't include unsupervised lab. time. Remember to include the revision week for lectures but not for labs, etc. Thus '2 hrs/week lectures plus 4 hrs/week labs' should yield 2*12 + 4*11 = 68.

Assessment [<Normal> and <Resit> require TC approval, rest freely variable]

This describes the assessment methods used.

The first compulsory Normal element describes the normal or sessional mode of assessment. Typical formats are:

  <Normal>1.5 hr examination (100%)</Normal>
  <Normal>2 hr examination (70%), continuous assessment
         (30%)</Normal>
  <Normal>Continuous assessment (100%)</Normal>

Don't spell out the form of the continuous assessment here, since this means having to tell Academic Office if it is changed. Put this in final explanatory <P> elements.

The second optional Resit element describes the normal or sessional mode of assessment. If omitted, a phrase like "As the normal assessment" will be generated automatically.

Typical formats are:

  <Resit>1.5 hr examination (100%) only</Resit>
  <Resit>2 hr examination (80%) with the continuous assessment
         carried forward (20%)</Resit>
  <Resit>1.5 hr examination (80%), supplementary continuous assessment
         (20%)</Resit>

You can then have any number of 'paragraphs' under the Assessment element, each enclosed in <P></P>. The values of P elements should contain all necessary punctuation. None of the P elements will be included in the module description supplied to Academic Office.

Typically these elements can be used for a description of the form of the continuous assessment, which can then be changed from year to year.

Example:

<Assessment>
  <Normal>2 hr examination (80%), continuous assessment
         (20%).</Normal>
  <Resit>2 hr examination (80%) with the continuous assessment
         carried forward (20%).</Resit>
  <P>The continuous assessment will take the form of a class test (5%)
     and an essay (15%).</P>
  <P>Hand-in dates are given on the module web page -- see the link
     above.</P>
</Assessment>

Summary [TC approval]

This consists of a single paragraph summary of the module. No internal mark-up is allowed. Keep to about 50 words.

Syllabus [Freely variable]

First there can be any number of introductory 'paragraphs', each enclosed in <P></P>. The values of P elements should contain all necessary punctuation but cannot contain other mark-up (except Code elements). The 'paragraphs' can give some general background or caveats. However, note that the intention is that the XML module description will be updated annually, so it's not generally appropriate to say things like 'Topics may change from year to year' here, since the syllabus should state what is to be covered in that year.

Then the actual syllabus should be given using any number of Topic elements, enclosing any number of optional Sub elements. Include all necessary punctuation. Ideally the Topic elements should make sense without any enclosed optional Sub elements.

Example:

<Syllabus>
  <P>Numbers in parentheses give the approximate number of
    lectures.</P>
  <Topic>Introduction to the course (1)</Topic>
  <Topic>Project Genesis (2)
    <Sub>How projects arise, choosing the right project, software life
      cycles.</Sub>
  </Topic>
  <Topic>Human Factors in Project Management (3)
    <Sub>Organizations and players in the game, interpersonal skills,
      project teams.</Sub>
  </Topic>
  <Topic>Basic Project Management Techniques (6)
    <Sub>Planning, estimating, monitoring progress.</Sub>
  </Topic>
  <Topic>Advanced Project Management Techniques (6)
    <Sub>Risk management, configuration management, quality management,
      process improvement.</Sub>
  </Topic>
  <Topic>Revision Lectures (2)
  </Topic>
  <Topic>Tutorials (4)
    <Sub>Introduction to course work, review of completed course
      work.</Sub>
  </Topic>
</Syllabus>

Books [See below]

You can give any number of books (previously only three were included in the Academic office module description). 'Books' can include lecture notes, etc. Please make sure that the bookshop, the University Library and the School Library are informed of any changes to your booklist. The main recommendations should not be changed during the teaching year.

The format of the XML for a single book is:

  <Book>
    <Title>Must be present</Title>
    <Author>Optional</Author>
    <Publisher>Optional</Publisher>
    <Year>Optional</Year>
    <Comment>Optional</Comment>
  </Book>

Example:

<Books>
  <Book>
    <Title>Lecture Notes</Title>
    <Author>P Coxhead</Author>
  </Book>
  <Book>
    <Title>Software Engineering (6th ed.)</Title>
    <Author>I Sommerville</Author>
    <Publisher>Addison Wesley</Publisher>
    <Year>2001</Year>
    <Comment>Main recommendation - earlier editions are also
      adequate</Comment>
  </Book>
  <Book>
    <Title>Software Engineering: a Practitioner's Approach</Title>
    <Author>R S Pressman</Author>
    <Publisher>McGraw Hill</Publisher>
    <Year>1998</Year>
  </Book>
</Books>

Links [Freely variable]

Here you put any the relevant web links. Since the format of a syllabus web page will be restricted somewhat by the XML, you may need to have a 'module web page' even if you didn't before. If so, the link goes here. However, you don't need to have links and this element can be omitted. The Links element consists of any number of Link elements. A Link element contains text plus <A href="..">..</A> mark-up. Note that although this deliberately looks like HTML, it isn't. XML is case-sensitive, so A must be capitalized and href must be lower-case. The closing double-quotes must be present. No other mark-up is allowed.

Note that a Link element does not have to contain an actual link, so you can have 'explanatory' paragraphs enclosed in <Link></Link>.

Examples:

<Links>
  <Link>See the <A href="/~pxc/nlpa/">NLPA web site</A>.</Link>
</Links>
<Links>
  <Link>NESTED EXPLICIT META-REASONING:
    <A href="/~jab/Courses/SEM3A7/nested-EMR.sp01.dvi">dvi</A>,
    <A href="/~jab/Courses/SEM3A7/nested-EMR.sp01.ps">postscript</A>,
    <A href="/~jab/Courses/SEM3A7/nested-EMR.sp01.pdf">pdf</A>.
  </Link>
  ...
</Links>

goTop of Page

goStaff Handbook