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 (9 regular workbooks, 1 extended 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 and completing the handin quiz. 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. And we will only know to look at your work if you complete the handin quiz.
In addition to handing in the workbook, each workbook will have an associated Canvas “survey” (I use the term survey and quiz interchangeably) 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) or the VSCode live server. 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.
Grading
Workbooks will be graded. Each workbook will have somewhere between 90-120 points. Grades are based on points, to get an A you need to score 90 or more points (see the grading scale on the Grading) page. 86 points (which is >= 85, but <90) is an AB - it doesn’t matter if the workbook has 120 or 91 points possible.
Your “workbook grade” (which is 64% of the total grade for the class) is the average of the number of points you scored on the 10 workbooks, dropping the lowest 2. However, you can only drop a workbook if you score 65 or more points. It is very important to complete all the workbooks and do at least amount (65 points should not be very hard if you are trying).
Basic 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).
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.
Doing advanced points is not a replacement for doing the basics. Advanced points are much harder than basic points. Advanced things often require you to do something hard to get a few points. Get the basic points first.
There is a limit to how many advanced points you can earn on each workbook. This is to prevent students from trying to make up for missing basic things by doing lots of advanced stuff.
Students may not earn advanced points for workbooks turned in late. If you are late with a workbook, we recommend that you do a good job on the basic parts, turn it in, and move on to the current workbook. In the past, what we found is that students would be late, they would try to make up for it by doing the advanced points, which would distract them from the next assignment, so they would fall farther behind. To prevent this, we disallow earning advanced points on late assignments and encourage students to focus on the basic points.
It is very important to do the basic parts of all workbooks. The workbooks build on each other. If you can’t do the basic parts of workbook N, you will have a tough time with workbook N+1.)
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 curves 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.
The time of submission will be considered as the latest of the handin survey time, the last commit, and the last push.
You may turn in workbooks up to one week late - no questions asked. Late workbooks cannot earn advanced points.
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 turn in the quiz on time, we will collect your assignment on time.
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 Workbook 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 advanced points or regrades.
Note: the workbooks have cutoffs. The definition of “very late” is “after the cutoff”. If you can complete the handin survey, then your assignment is not very late and you do not need to complete the very late form.
Note: the penalty for a very late assignment is at the discretion of the course staff and may be assessed later in the semester when we can make a more holistic assessment. A student who is very late once may receive less of a penalty than a student that is chronically very late.
If you have a medical or personal issue, we can make alternative arrangements. Contact the professor (this is one situation where email is OK). In general, we will ask that you follow the very-late procedure.
Note: no assignments may be turned in after the last day of class, except for the final project workbook.