Updating my course webs
Topics/tags: Teaching, technical, Web, rambly
For the past week or so, I’ve been preparing my course webs [1] for my spring semester courses. And, as I wrote a year or so ago, I manage to find ways to make the process more complicated than it should be. Like many members of this department, I use custom software to build my course webs. In particular, following the lead of one or more of my colleagues, I use Jekyll for building each site and some Bootstrap for the design. However, I’m not great at using either, and it appears that I lack either the time or the mental capacity to get significantly better.
Because my colleagues know the tools better, their sites tend to evolve more quickly than mine. Unfortunately, I can’t just copy from their site to mine because we think about course webs somewhat differently. One obvious example is the sets of links at the top of each page. The colleague I borrow from most recently likes a set of eight or so links [2]. In contrast, I prefer hierarchical menus [3]. Another is that I tend to integrate my live lecture notes [7] along with tools that automatically extract information from those notes.
In any case, one stumbling block I thought I was hitting as I prepare for next semester has to do with the schedule. My colleague not only rearranged the visuals for the schedule to make it much more readable, but also changed the way we’re storing data. In particular, they have a single file that contains dates and detailed information on what is covered each day. You can see some code in Appendix A.
I prefer to separate the semester-focused material, such as the dates of classes and the due dates of assignments, from the information on the individual topics I teach. One advantage of the latter approach is that it’s much easier to rearrange topics [8,10]. In my world, one should have three files, rather than one: the detailed information on each topic (see Appendix B), the information on the dates for the semester (see Appendix C), and the information on assigned work (see Appendix D).
In case it’s clear, we both believe in the principle of DRY data [11]: Each piece of information should reside in a single place, and every page that needs that information should pull it from that place. We just differed on what the places should be. At least we both moved forward from putting the information in the individual files.
I could have ignored my colleague’s changes to the appearance of the schedule. However, their schedule looks much nicer than mine. As importantly, it appears to print in a more convenient form. That meant that I had two choices: I could adapt their strategy for structuring data or I could rewrite their code for generating the syllabus and other parts of the site.
Can you guess what I decided?
That’s right; I’m much too tied to the way I like to arrange data. So I sat down and figured out how to rewrite their code.
It’s always a challenge to work with the array of languages associated with Jekyll. We use YAML for the data specification, Liquid for much of the processing, Ruby for a few things, JavaScript for live activities on the page, and HTML and Markdown for the content. Most of these languages make sense to me, but I always wonder why anyone would have chosen to adopt Liquid as their programming language; it’s not bad for a narrow range of tasks, but there’s a lot of extra work involved in getting more sophisticated things done. And I really miss the ability to use regular expressions.
One advantage of spending the time figuring out how they were building the schedule and how to adapt it to my data model was that it was then easier to add features to the schedule. For example, we tend to write both a short description of each class day and a list of topics we plan to cover. My colleague’s schedule shows only the short description; I added the list of topics [12]. I also like to refer to class days by number, and so added a note about the class number to the schedule. You can see the current draft schedule on the course site for CSC 151.01 2019S.
Perhaps as importantly, I learned enough about the structure of their code that I was able to build a new variant of the schedule, which I call the schedule overview. This more concise version lists all the topics and major due dates in more of a grid form, with one row for each week of the semester. I find these grids easier to read when I want to quickly understand a course. I expect it will also be useful for students who want to plan their work for the semester and for other faculty who want to get a quick sense of what we cover in the course.
Now that the technology and the draft schedules are in place, I can move forward with the next important step: Updating and finishing all of the readings and labs. It should be fun.
Postscript: Mustn’t forget: I may be putting the 151 labs on a separate site. In that case, I’ll need to rethink some of the menus and such. Oh well; that’s a task I can put aside until we’re slightly closer to the start of the semester.
Appendix A: The start of a course data file in my colleagues’ form
"Week 1":
"2019-01-23":
topic: Introduction to Algorithms
abbrev: intro-algorithms
summary: |
We begin the class by exploring the definition of computer science and by
trying to write some basic algorithms.
subjects:
- Introduction - What is CS?
- Exercise - An everyday algorithm
- Debriefing on exercise
- Common parts of an algorithm
assigned:
- page: /assignments/assignment1.html
"2019-01-25":
topic: Getting Started with Linux and Scheme
abbrev: intro-linux
summary: |
We begin to consider the content and structure of the course. We also
prepare ourselves to use our laboratory environment (that is, the Linux
workstations and the DrRacket Programming Environment).
subjects:
- Getting started with Linux
- Why use programming languages?
- Scheme history
- Scheme basics
- Using DrRacket
reading:
- page: /readings/algorithms.html
- page: /readings/linux.html
- page: /readings/drracket.html
- page: /readings/beginning-scheme.html
lab:
- page: /labs/linux.html
- page: /labs/starting-scheme.html
"Week 2":
"2019-01-27":
message: _Work Due_
due:
- page: /assignments/assignment1.html
time: 10:30pm
Appendix B: The start of a topics file in the form I prefer
Note that I have not yet decided where the readings and labs will reside, so I have their names in place of the links.
- topic: An introduction to algorithms
abbrev: intro-algorithms
summary: |
We begin the class by exploring the definition of computer
science and by trying to write some basic algorithms.
subjects:
- Introduction - What is CS?
- Exercise - An everyday algorithm
- Debriefing on exercise
- Common parts of an algorithm
- topic: Getting started with Linux, HTML, and CSS
abbrev: intro-markup
summary: |
We begin to consider the content and structure of the course,
exploring both our laboratory environment (Linux workstations)
and mechansisms for representing and styling text.
subjects:
- Getting started with Linux
- Generalized markup with XML
- Web markup with HTML
- Page styling with CSS
reading:
- link: Introduction to FunDHum
- "An introduction to Linux"
- "Generalized document markup with XML"
- "Writing Web Pages"
lab:
- "Writing Web Pages"
- topic: Getting started with Racket
abbrev: intro-racket
summary: |
We consider Racket, the programming language we will use
throughout the course.
subjects:
- Why use programming languages?
- Scheme history
- Scheme basics
- Using DrRacket
reading:
- "Algorithm building blocks"
- "An introduction to DrRacket"
- "An introduction to Racket"
lab:
- "Getting started with Racket"
Appendix C: The start of a dates file in the form I prefer
- week: Week 1
anchor: week01
days:
- { date: 2019-01-20 }
- { date: 2019-01-21 }
- { date: 2019-01-22 }
- { date: 2019-01-23, class: true }
- { date: 2019-01-24 }
- { date: 2019-01-25, class: true }
- { date: 2019-01-26 }
- week: Week 2
anchor: week02
days:
- { date: 2019-01-27 }
- { date: 2019-01-28, class: true }
- { date: 2019-01-29 }
- { date: 2019-01-30, class: true }
- { date: 2019-01-31 }
- { date: 2019-02-01, class: true }
- { date: 2019-02-02 }
Appendix C: The start of a dates file in the form I prefer
- date: 2019-01-23
assigned:
- page: /assignments/assignment01.html
- page: /assignments/assignment02.html
- date: 2019-01-27
due:
- page: /assignments/assignment01.html
time: 10:30pm
- date: 2019-01-29
due:
- page: /assignments/assignment02.html
time: 10:30pm
- date: 2019-01-30
assigned:
- page: /assignments/assignment03.html
[1] I use the term course web
to mean Web site for a course
. But you
probably figured that out already.
[2] Home, Schedule, Readings, Labs, Assignments, Exams, Project, and Syllabus.
[3] Primary, which includes links to the front door [4], the course news, the course schedule, the course syllabus, my appointment software, and my statements on a variety of topics. Current, which includes links to the current assignment, eboard, exam, flashcard assignment, lab, lab writeup, and reading. Resources [5], which includes links to the lists of assignments, eboards, exams, flashcard assignments, labs, lab writeups, and readings. Reference, which links to some important reference materials [6]. Related Courses, which links to some other recent offerings of this course. And Misc, which provides links to other resources.
[4] Home page
, in some people’s parlance. However, Home page
is
ambiguous; it can be where I start my explorations (origin
) or where
you enter the site (front door
).
[5] I used to call this Sections
, but that seemed to imply sections
of the course, as opposed to sections of the Web site. I don’t like
Resources
. I guess I’ll have to come up with a new name.
[6] Someday, it will once again link to full 6P-style documentation for all the procedures we use.
[7] Eboards
, for those who attend my classes.
[8] Do I rearrange topics more than my colleagues do? I’m not sure. Certainly, I rearrange topics multiple times during the weeks leading up to the start of the semester. There are also two or three times each semester in which I find that a topic needs an extra day, so I need to shift everything afterwards up to the next pause for breath [9].
[9] I got the idea of a pause for breath
from John Stone and Henry
Walker. It’s a day in the schedule with no planned topic that provides
some room to allow one to adjust the schedule if something takes
longer. If there’s not a need to adjust the schedule, we find an
interesting bonus topic to discuss or give students a class period to
work on homework with faculty and mentors available for help.
[10] While I rearrange topics, I do my best not to rearrange the due dates of major assignments. I know what havoc such rearrangement can play on students’ plans.
[11] Don’t repeat yourself.
[12] I realized how important the list of daily topics was when I started putting together the schedule for CSC 207 and found myself reading through old class schedules.
Version 1.0 of 2019-01-05