Workbooks are an experiment for the Spring of 2019. Please bear with us while we work out the process.
The idea is that workbooks will connect reading, assignments and programming together. It will make reading code and experimenting to understand how things work explicitly part of the assignment. It 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 (including make web pages).
Each workbook will contain.
- index.html – This file will contain the instructions. Start Here! Be sure to view this page (and all html files in the workbook) using a local web server. (see Tools for advice on local web servers). You will not need to modify the index file.
- README.md – This is a file that you (the student) will fill in to describe your assignment. You must fill in the README file for all workbooks! Your readme file must include your name, your GitHub ID, and your WISCID.
- QUESTIONS.md – This is a file that you (the student) will fill in, answering questions. We will put the questions as Markdown headings (lines beginning with # – we may have additional text explaining a question). Please leave the questions (and text) we provided in the file – you should only add your answers to the file.
- other html files – We will provide html files beyond the index file. They will be explained in the html file. You should always look at them using a local web server (just in case they need it). You may be asked to read and modify html files (other than the index). You are welcome to read any of the HTML files – even if they aren’t required reading.
- art assets – We will sometimes give you “art assets” (images, 3D models, …). We will put these in a separate directory, and document them with a README file. If you add new art assets, you should document them in the README file for the whole workbook.
If you add any file to the workbook, make sure to say so in the README.md file, and to have a comment near the beginning saying what it is. If you add a new file, be sure to add it to the repo (using the GIT “add” command)
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.
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.
Answering the questions in the “QUESTIONS.md” file is required. We will check that you have answered the questions, but will (usually) not check your answers. We will (usually) post sample answers after the assignment is due.
You are responsible for the content of the questions. They can give you an idea of what to expect on the exam, or what we expected you to learn from the readings and looking at the workbook materials.
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.
What can you change / add?
We will tell you what files that you should add/change as part of the index.html or assignment description.
You will always need to change the README.md and QUESTIONS.md files. Even if we forget to remind you.
We ask that you do not change any of the library files (including ones that the course staff) writes.
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.
Workbooks will be graded. See the CS559 Course Policy Page page for details.
You cannot get an A on a workbook. However, you can get “bonus points” (which will be explained in the assignments). If you collect enough bonus points over the course of the semester, you can get a 1/2 grade raise (e.g. AB to A).
The workbook directory must have a
README.md file. If there isn’t a starter one, create and add it.
You must edit the
README.md file to (at least) put in your name, your GitHub ID, and your wisc ID. For me this would be:
Michael Gleicher GitHub: gleicher WiscID: mlgleicher
README.md is also the place to give attribution for any code or other work that you got from someone else, and to explain what you did or did not do in the assignments.
See CS559 Course Policy Page for details.
Workbooks are due on Friday (12:01 Saturday is not Friday). However, we will accept late workbooks until the following Monday. We will collect the workbooks early Tuesday morning. Workbooks not turned in by this deadline will not be graded.