Workbooks
Workbooks are the main assignments for class and the required reading. Understanding them is realy important.
There will be a workbook each almost every week (10 regular workbooks, 1 advanced workbook, 1 “final project workbook,” no regular workbook the weeks of exams).
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. We recommend using Visual Studio Code’s Live Server.
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 “survey” that asks you questions about your work. We will not grade your workbook unless you complete the “survey” - 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 “survey”. While you can re-do the survey, you may need to re-enter all of your answers.
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, generally, everything in for_students). 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.
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).
Sharing with Course Staff
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. We only know to harvest our copy when you turn in the survey. So don’t forget to turn in the survey.
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 describe on Tools for 559). We recommend that you use Visual Studio Code for Development.
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.
Basic Points and Advanced Points
The workbooks vary in size and difficulty. Even with a given workbook, there are things that we expect everyone should be able to do (these are the basic points), and more advanced things that are harder (these are advanced points). For the project workbook, we don’t make this distinction.
In terms of grading, if you only do the basic parts (even perfectly), your grade is limited (it maxes out for a low AB). However, doing advanced things doesn’t mean you don’t also need to demonstrate the basics.
In terms of score… Each workbook will have 84-87 basic points. (on the 100 point scale, 80=B, 85=AB) so if you do perfectly on the basic points you will be in the B-AB range. If you want to get a better grade, you have to get some advanced points.
Generally, each workbook will have around 3-10 advanced points available. These are harder to get. The workbooks are designed so its easy to get all the basic points, and harder to get advanced points. Some workbooks have more points available, but we limit the amount you can apply to your grade, so you cannot make up for missing basic stuff. Advanced points are also harder (if you want 85 points, getting 75 basic and 10 advanced will be more work than just getting 75 basic).
Where this gets complicated: not all workbooks have the same number of points. Some have more or less advanced points. There is some variance in the number of basic points. If a workbook is easy, it may only have basic points, so you cannot “get an A” on it. The way you get an A is by getting enough advanced points over the course of the semester.
This scheme gives you (the student) some flexibility. You don’t have to do all the advanced things every week. If you want an A, you need to keep up with the basic stuff, and then do “enough” advanced stuff over the course of the semester. If there’s some week where the material is less interesting to you, or you have too much work in your other classes, you can do less advanced work that week and make up for it in other weeks.
Note: there will be a workbook that is only advanced points. It is optional. There will be enough other advanced points that you can get an A without doing it. But it will be a source of a lot of advanced points if you are trying to get them.
Grading
Workbooks will be graded.
See the Policies page for policy details.
The “final project” workbook is simply graded on the A-F scale. (we’ll give you a number that corresponds with your grade).
For the rest of the workbooks… Think of the workbooks in terms of points, not percentages, even though the points are measured on the 100 point (A>=90, AB>=85) grading scale.
For any given workbook, you can approximate your grade by taking the basic points and adding the advanced points (up to the maximum you are allowed to earn on that workbook). This is generally a lower bound on your grade.
But, for the final grade, it is not the simple average of these scores - we account for the fact that different workbooks have different numbers of points available, not everyone does great on everything, and we want students to have flexibility in how they get advanced points.
For your final workbook grade, your basic score is the average of your basic scores, dropping the 2 lowest grades on workbooks that you score more than 50 points. Note: if you score 0 (you don’t turn in a workbook) you cannot drop it. This is to make sure that everyone at least tries each workbook.
Your advanced score will be a function of the sum of all the advanced points you earn (obeying the caps on how many you can earn on each workbook) over the course of the semester. There are about 100 advanced points available over the course of the semester, so you can (roughly) divide by 10 (for 10 workbooks). This is a lower bound. (last year, 25 advanced points would have added 10 to your score - but there were fewer advanced point opportunities). The “function” may max out (last year, there was a maximum points to earn).
Your workbook grade (on the 100 points A=90, AB=85, … scale) will be the sum of your basic score and your advanced score. So, for example, if you averaged 80 for the basic parts of all the workbooks, and scored 50 advanced points over the course of the semester (which, by crude estimate, gives you 5 points), that would give you 85 for your workbook grade.
Excess: If you earn “excess” points (e.g., more advanced points on an assignment than the max you can use), we do keep track of them. At the end of the semester, if your grade is near a borderline, we may consider them.
Artistic Merit: This year, we will not explicitly give points for artistic merit. It was too subjective, and too contraversial. However, we will keep track of notable assignments (things where you make something cool). We won’t give you points, but we might reward you some other way (such as if your grade is near a borderline). Also, we will post cool things from assignments in the gallery.
Regrades: Requests for workbook regrades must be made using the Regrade 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.
Deadlines and Late Policy
Regular workbooks are due on Monday, Madison time. If it is 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 survey must be completed to signal us that the workbook is ready for grading.
The final project workbook and the special “advanced only” workbook will have a different and specific late policy.
Workbooks will be collected from GitHub sometime after the Monday deadline. Probably early Tuesday morning. So be sure to turn things in on (or before) Monday in order to have them graded. Both the GitHub commit/push and the handin survey must be turned in on time.
You may turn in workbooks up to one week late - no questions asked. Late workbooks cannot earn advanced 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.
We discourage students turning in workbooks “very late” (more than 1 week after the deadline), but we will accept them in exceptional circumstances. Turn in a “very late” assignment by uploading it to GitHub, completing the handin survey, and completing the “very late” form where we will ask you why the assignment is very late. The penalty for a very late assignment is at the discretion of the course staff. It is important that the “very late” form is completed (so we know that we need to grade the assignment, and have information so we can decide on the penalty). Very late handins are not eligible for regrades or “do-overs”.
If you have a medical or personal issue, we can make alternative arrangements. Contact the professor (this is one situation where email is OK).
Note: no assignments may be turned in after the last day of class, except for the final project workbook.