Workbooks

January 12, 2021 (Last Modified: March 3, 2021)

Workbooks are the main assignments for class and the required reading. Understanding them is realy important.

There will be a workbook each week (12 in total - the last workbook is a bigger “final” workbook that takes 2 weeks).

Workbooks are small web sites with web pages and code that you will read and write. They serve as both programming assignments (your programs will be inside of the workbooks) and reading assignments (you are responsible for the content of the workbooks as well as the listed required readings in the workbooks).

Each week, you will get a workbook from Github (see Git and GitHub in CS559 (How things will work)). You’ll read the text of the workbook, experiment with the code in the workbook, and make additions as directed. When you’re done, you’ll commit your work and push it back to GitHub, so the course staff can grade it.

The idea of the workbooks is that they explictly bring together the tutorial aspects of class (reading and demos) with the programming aspects (things you write). The reading assignments will be given in the workbooks. This means the text of the workbook web pages, but also the source code of the workbooks, and other documents that the workbooks point you towards. Reading the code in the workbooks and experimenting with demos will often be an explicit part of the assignments.

All of the programming you do in class will be in the workbooks. You will fill in parts of the workbook with code as directed. Workbooks will give you framework code for bigger assignments, and help with the mechanics since we’ll make sure the files are in the right place. And since it will all be tracked with GIT, making it easy to turn it in (in theory), and protecting you against messing things up (providing you use GIT correctly).

Part of the idea of the workbook is that reading the code for examples should be an active part of class. For many things we really want you to look at how we do things.

Workbook Contents

You should start at the root of the workbook (the index.html file in main directory). This page will lead you through the pages of the workbook. They are usually numbered, and are designed to be read in order.

The pages have “sub-pages” embedded in “boxes”. These pages are designed to fit on the content pages which discuss them, but they can also be examined independently for easier debugging. Boxes are explained in Workbook 1.

You must look at the workbook using a local web server. Simply opening the workbook pages as files does not work. See Tools for 559 (Local Web Server) for more details.

The only files you should change are the ones in the “for_students” directory. (unless we give you explicit instructions otherwise)

Remember that you must commit your changes to the files (including additions of new files) to the repository! We recommend committing often, so you have a log of your work. (see the Git and GitHub in CS559) page

If you add a new file, be sure to add it to the repo (using the GIT “add” command). Generally, you won’t need to do this - you will edit files that are already created by the staff and placed into the workbook.

Turning in Workbooks

You turn in the workbook by pushing to your repository on GitHub. See Git and GitHub in CS559 for an explanation. We will only see the work that you (1) commit to your local repository and (2) push to the repository that GitHub classroom created for you.

In addition to handing in the workbook, each workbook will have an associated Canvas “Quiz” that asks you questions about your work. We will not grade your workbook unless you complete the “quiz” - it will ask for information we need for grading and serves as a signal that your workbook is ready for grading. There may also be questions in the quiz that are worth points toward the workbooks.

Generally, we suggest you turn in the workbook (commit and push your final version) and then do the “quiz”. While you can re-do the quiz, you may need to re-enter all of your answers.

Note: in past years, we asked students to edit the README.md file in the workbooks. This year, you don’t have to edit this file - we are using the handin “quiz” for that purpose.

Markdown

You may simply put plain text into the Markdown “.md” files. Using markdown formatting is optional. The course staff will not run your files through a converter, but we may look at it using an editor (like Atom or VSCode) that is Markdown aware.

What can you look at?

You are allowed to look at everything (all files) in the workbook! In fact, you are encouraged to look at things to figure them out. You might not want to try to look at the library files (especially when we get to THREE), but you are allowed to.

The content of the workbook pages are required reading for the class.

Some of the HTML and JavaScript source files you will be required to look at (we will tell you). Think of them as required readings, just like textbook chapters and the content of the workbook pages. We will discuss things in code comments, and expect you to learn from our example code.

The files that you should look at will be in a special directory to make them easier to find.

What can you change / add?

We will tell you what files that you should add/change.

You should not change any of the library files (including ones that the course staff) writes - unless we specifically instruct you to do so.

In general, you should avoid changes parts of files that you don’t need to change. You may accidentally break things (if you break our part, it will be harder to figure out that your parts work) or make things difficult for the graders.

If you accidentally make changes, you can always use GIT to get back to the original (the joy of using source control).

The course staff has access to your repository on GitHub. If you want to share your work with the course staff (for example, if you want to show your program), you can push it to your repo and they can clone it.

If you are coming to consulting hours for help, be sure to push your work so the staff can clone it.

And, of course, we can only grade what you commit and push to the repository before we harvest our copy.

Grading

Workbooks will be graded. You will receive a grade on the “100 point scale” (A=90, etc - see Grading) for each workbook. We will drop your lowest 2 non-F workbook scores. The last workbook (Workbook 12 - Graphics Town) counts double and cannot be dropped.

See the Policies page for policy details.

While workbooks are graded on a 100 point scale, they have different numbers of points available. Rather than having an equal number of points, the workbooks vary. On average, you have the opportunity to earn approximately 100 points per workbook. But each individual workbook will vary.Some workbooks have only basic assignments, so there is no opportunity to get more than 80-85 points. Other workbooks have many opportunities for advanced work, and you can score more and 100 points.

For each workbook, we divide the points into 3 parts to help your planning:

Basic Points: Each workbook will have between 80-85 “basic points”. These are parts of the assignments that we expect everyone to do.
Bonus Points: Almost all workbooks have the opportunity for a number of bonus points (typically 10-20). These are typically harder problems that you should do after completing the basic parts. These points tend to be harder to earn (more work per point), and check for more advanced features.
Artistic Merit Points: The grader may, at their discretion, award “artistic merit” points for assignments that are particularly creative. Usually, this is 1-3 points. It is totally at the subjective discretion of the grader. Artistic merit points are a way a grader can give a reward for making something cool (cool assignments make grading more fun for the grader). They may not be given all the time.

The idea of this scheme is that everyone should do the “basic” work required to get a baseline grade (the 80-85 points give a B/AB). Students who are interested in the more challenging problems, or just want a better grade, need to do “enough” bonus points over the course of the semester. The bonus point scheme is designed to be flexible: we don’t expect everyone to do amazing work every week - as long as you do enough “bonus” work over the duration fo the semester, you can get an A.

At the end of the semester, we determine your workbook grade (which is 65% of your final grade) by combining the three kinds of points. Your basic point average (dropping the two lowest non-F grades) gives your baseline grade. Your bonus and artistic metric points add to that. You keep the bonus and artistic points you earn, even if we drop the assignment.

Regrades: Requests for workbook regrades must be made using the Regrading Form within 1 week after the grades are posted. See Regrade Policy for more details. Artistic merit points will not be rewarded as part of a regrade.

Execution Environment

The workbooks only run if you use a local web server. You cannot just open the HTML files.

For grading, course staff will use the npm “http-server” (which we recommend on Tools for 559). You may use something else for development (live server in Visual Studio is a great choice for testing). But, be aware, this is what we will use for testing.

For grading, course staff will use an up-to-date version of the Chrome web browser. You may use something else for development, but check that your program is compatible with Chrome. We have found that programs tested in Firefox generally work in Chrome. Students have had problems with using Safari.

Deadlines and Late Policy

Late Policy for Workbooks

Workbooks are due on Monday, Madison time. If it’s 12:01 Tuesday, then it’s not Monday. Remember, that you need to push your repository to GitHub for us to get it, and that the workbook quiz must be completed to signal us that the workbook is ready for grading.

Workbooks will be collected from GitHub sometime after the Monday deadline (following the Friday). Probably early Tuesday morning. So be sure to turn things in on (or before) Monday in order to have them graded.

Workbook 12 will have a different and specific late policy because of the need to grade it before the end of the semester.

You may turn in workbooks up to one week late. Late workbooks cannot earn bonus points. If you are late on one or two workbooks, there will be no penalty. If you are late on many workbooks, we may deduct a penalty from your overall workbook grade (the one computed by averaging).

Remember that filling out the Canvas quiz that for the Workbook is part of turning it in. We will only grade assignments for which the Canvas quiz has been completed.

If the quiz is completed before the deadline, we will assume that the assignment is complete before the deadline and will clone it at the deadline. There is no opportunity to change your mind and turn the assignment in late.

For late assignments, we will use the quiz as a signal that there is an assignment to grade. Submit the quiz after you have submitted the workbook (via pushing it to the repository).

If you submit the workbook on time (which includes the quiz), you can update it up until the deadline. However, you cannot update it after the deadline.

If you are submitting the workbook late, you must do the quiz after you have pushed your work. You cannot update it after you submit the quiz.