Waterfall.

Single-source Course Syllabus in XML

June 2023

Every academic institution mandates the creation of course syllabi: documents that outline the purpose, scope, policies and assignments that students undertake for a semester. Increasingly this has become a central task of the instructional designer.

One of the difficulties in creating these documents is ensuring that each student receives accurate and consistent information, particularly with respect to administrative rules and deadlines. When I was a university professor, an audit of my syllabi showed that six different courses shared the same policies, instructor information, and grading system. I was repeatedly cutting-and-pasting updates in a word processor. Because manual cut-and-paste is mistake-prone, I was never certain that all the syllabi had the same required content, and students complained that they were unable to receive up-to-date information.

Then one semester, I converted my syllabi to XML and developed a simple single-source system. This system enabled me to better separate course-specific content from general administrative content. Student complaints decreased, and changes took less time. In this article, I present my method for creating and managing the single-source syllabus. Although the technical knowledge of the XML is not too sophisticated - - my main purpose is to focus on the method of single-sourcing and instructional design rather than technical skills - - you will nevertheless need access to the following: the MS Internet Explorer Browser (version 7 or higher); a text editor; and knowledge of XML, XSLT, HTML and CSS. Review this lesson with the accompanying file download called xmledsystem.zip.

What is Single-Source?

The Society for Technical Communication defines single-source as "using a single document source to generate multiple types of document outputs; workflows for creating multiple outputs from a document database." A key practice of single-sourcing is reusability. Reusability is the capacity to develop text one time, archive it in a single place, and transport it upon user demand for multiple contexts, interfaces, and formats.

Graphic compares traditional and new precedence practice.

Creating reusable content requires a movement away from traditional writing that proceeds in a linear or hierarchical manner. The precedence of traditional writing and reading generally moves down the page. By contrast, single-source writing is modular, consisting of nested nodes. Access involves a precedence that proceeds from inside-out.

A proper application of single-source methods requires good planning in the early stages. Typically, this planning involves many steps that rely on a team of people trained in usability, technical writing, and software development. For purposes of our very brief and abbreviated example, a simpler approach will suffice: a content audit; creation of content modules; and a structural build-out.

Content Audit

A content audit is an inventory of existing documents and assessment of the procedures for document production (Rockley 2003 104-107). To illustrate the process, let us take excerpts from two of the six syllabi mentioned in the example for analysis. (See "syllabus130.docx" and "syllabus320.docx" in the xmledsystem.zip archive.)

Snapshot of Excel spreadsheet. Left column lists the section of the syllabus. Right column lists whether the section is unique to one syllabus or shared among many.

Note that the course descriptions (About, Required Materials), specific assignments (term papers, exams, projects), schedule and some policies are unique to specific courses. By "unique," I mean content that is specific and usable for only one course. By contrast, the statement immediately under the Assignments heading is shared between courses, as is the policy on Attendance, Involvement, Engagement and Participation. We will call these content modules "shared" content.

A helpful rubric for conceptualizing unique and shared content is the reuse map. A reuse map is a spreadsheet that displays unique and shared information "at-a-glance." Ann Rockley’s Managing Enterprise Content (2003) provides several examples of more sophisticated reuse maps for an enterprise-level system. We aren’t working with anything nearly that large here. Nevertheless, a simplified map should help clarify where content is located. Any cell with a "U" indicates content unique and different between courses. Any cell with an "S" indicates content that is shared.

This map lays out the areas of the two syllabi that have unique and shared information. According to it, there are two areas of shared information with which we need to be concerned. The rest of the information is unique to specific courses. Keep in mind here that we are dealing with abbreviated syllabi only for example purposes. Real syllabi are likely to have many more areas of shared content.

Creation of Content Modules

With the reuse map in hand, we can now move to modularization of content. Dividing up documents into modules ought to take place with a sense of the genre in mind. A syllabus will typically have the following structure and sequence:

For purposes of this exercise, the smallest usable module will be a paragraph in a section. However, in other situations, you may decide that it could be smaller (for example, a sentence or word). Since the Policies section of both courses contains a mixture of both shared and unique content, we will use it as an example. Modularizing the Policies section of both syllabi, we have the following scenario:

Modules for Course Syllabi
Course 130 User Interface Design: Course Policies Course 320 XML and Single-Sourcing: Course Policies
Technical Support (This policy only applies to this course.) While you are welcome to use whatever software and hardware you want for the course, I do not have the resources to be your technical support resource or troubleshoot technical problems with your PC or with the required software. Because I/we have no way of addressing the particularities of each computer system, you will need to take primary responsibility for configuring your own home computer setup. If you are in a lab on campus and you have technical support questions, you need to contact ITS or the lab administrator in the lab you happen to be working in. For technical problems with the CU-Online/Blackboard site, please contact their help desk.
Revising Projects (This policy only applies to this course.) Any project except a quiz, exam or presentation may be revised but not for full credit. The highest total score on a revised project is B+. So, if you get an A-, revising the project will actually LOWER your score. This is only fair to the students who received higher grades the first time.
Attendance, Involvement, Engagement and Participation. (This is a policy of all the courses). Because this is an online course, primary responsibility for learning rests on the shoulders of students. There will be opportunities to interact with other students throughout the semester as well as with me using forums and other utilities provided in the e-college space. You are advised to take advantage of these opportunities when they arise. Proper etiquette and civility is a basic requirement for participation on these discussion fora.

In these two examples, we have created the rubric for a modular structure that marks off parts of the documents as unique to a specific course and parts of the document as reusable.

Structural Build-out

If you have not done so already, download the xmledsystem.zip file and unpack it into a folder on your computer. Load the file callpolicies.xml into Internet Explorer 7 to get a sense of how the system works. You should get a screen that looks like the following:

Screenshot of User Interface Design syllabus.

Now, load the file called callpolicies130.xml into a text editor. The XML markup for the Policies section of my User Interface Design syllabus looks as follows:

Graphic of XML markup of the Policies section.

For the moment, let us skip the XSLT code and analyze the document structure. Focus your attention on the <policies> node, and notice that there are two <contents> regions nested within it. The first <contents> node contains the shared policies for both courses. This document is written as an external entity referenced in the courses.dtd file:

Picture of the entity declarations in the DTD section.

The external entity allows XML to load shared content into other documents. A reference to the same entity is placed in the callpolicies320.xml file:

Displays the contents of the shared policies entity.

Sharedpolicies.xml contains the following:

<h2>Attendance, Involvement, Engagement and Participation</h2>
<p>(This is a policy of all the courses). Because this is an online course, primary responsibility for learning rests on the shoulders of students. There will be opportunities to interact with other students throughout the semester as well as with me using forums and other utilities provided in the e-college space. You are advised to take advantage of these opportunities when they arise. Proper etiquette and civility is a basic requirement for participation on these discussion fora. </p>

The inclusion of the external entity reference to the module sharedpolicies.xml allows the Attendance policy to appear for any course containing the reference. We do not need to cut-and-paste this module across documents: it is reusable as an external entity reference. If a change to the policy occurs, the change need only be made in this module, and it will immediately be accessible by the other course syllabi.

Try an update for yourself. Look at the current policies section of the User Interface Design syllabus, which should appear as follows:

Display of User Interface Design Policies section.

Suppose that your school has instituted a new rule allowing students to bring dogs to class. Insert the following statement into the sharedpolicies.xml file as follows:

<h2>Bringing Dogs To Class</h2>
<p>Because of the benefits animals bring to people who study, students are permitted to bring dogs to class.</p>

Save the sharedpolicies.xml file and reload the Policies page of the User Interface Design Syllabus. It should now read as follows:

Updated User Interface Design Syllabus Policies section.

Now load the Policies page for XML and Single-Sourcing. Notice that without doing any other editing, the same change is instantly available in the 320 syllabus:

Updated Single Sourcing Syllabus Policies section.

The use of external DTD entities is one of several XML techniques for managing reusable content. (Alternatives include the use of the document() function in XSLT and schemas.) Notice, too, the use of basic HTML tags in the sharedpolicies.xml file. By restricting the number of tags, the system could be shared with other faculty who do not know XML very well. An instructor can be trained to use a handful of tags and make good use of the system.

The documents contain one additional portion of reusable text not discussed until now: the references to head130.xml and head320.xml. These XML documents allow one to specify content for the html <HEAD> section and linkbar that is reused for each page of a syllabus of a particular course. Head130.xml is as follows:

<headsection>
<title>130: User Interface Design and Analysis</title>
  • <aboutlink>callabout130.xml</aboutlink>
  • <assignmentslink>callassignments130.xml</assignmentslink>
  • <policieslink>callpolicies130.xml</policieslink>
  • <schedulelink>callschedule130.xml</schedulelink>
  • <othercourse>
  • <title>XML and Single Sourcing</title>
  • <link>callabout320.xml</link>
  • </othercourse>
  • </headsection>

    A crucial and often overlooked component of content reuse methodology is the development of a meaningful file structure. The file structure will determine the relationship between content modules that are reused and those modules that remain unique to specific courses. At present, the portions of the system we have been discussing have the following file structure:

    Flow Chart of File Structure.

    The documents are processed using the built-in XSLT processor that comes with Internet Explorer 7. Thus, they are processed client-side. Carefully examine the XSLT files for specific template rules. The current version transforms the XSLT to HTML. A global stylesheet is applied to the syllabus. Note that the syllabus system reuses XSLT code in a way similar to the XML files. The file structure for the XSLT components is listed below:

    Flow Chart of File Structure.

    Conclusion

    With some knowledge of XML and a little luck, you should be well on your way to creating a modular and usable syllabus management sytem. Of course you may use and modify the xmledsystem.zip files as you see fit, but I do ask that you preserve the author attribution and link to my website inside the documents.

    © June 2023 Filipp Sapienza.