CS 333: Writing Reference

README

You are expected to turn in a README.txt file with your source code for every project except the last one. The README file is to give users insight into what your code does and how to use it. For example, it lets the graders and Professor know how to compile and run your code. It is also a good way to remind yourself of the details when you want to reuse your code later.

A single README file serves for all source code in your submission, including both C and the selected languages if there are coding tasks for them. The README should contain the following information.

• Project identifier, your name, and the submission date.
• The directory layout for your handin folder. You can use the Unix tree command to generate this.
• Your operating system and C compiler (e.g. use gcc --version).
• For each task, the compile, usage, known bugs, and expected output of each program. You should not include the actual output of running the program unless it is short, just a description of what the output means. This should include both your C programs and programs written in other languages.
• Your answers to any questions in the C tasks. Put your language question answers in the wiki report.

You can use this README template.

To check whether you've made your README file clear, you may ask yourself the following questions:

• Does the README file identify the purpose and author of the directory's contents?
• Does the README file list every other file in the directory along with a short description of its purpose?
• Does the README file use spacing and indentation to make its organization easily comprehended by the reader?
• Does the README file include the compilation environment (i.e. the operating system it was developed on and the version of the compiler/interpreter that was used in development)?
• Does the README file describe how to install (if necessary), compile (if necessary), and run the any programs in the directory?
• Does the README file describe any command line arguments necessary for running programs in the directory?
• Does the README file describe the outputs of programs in the directory?
• For the C assignments in CS333, the README serves as the report (for just the C-programming part). If your README is part of such a project, does it contain the information required by the tasks in the C-programming part of the project instructions? and only those?
• If you have undertaken any coding extensions, does the README have a description of them?

Report

Your wiki report is the main platform for your selected languages in CS333. The final product of this writing should be a tutorial for your selected languages. A good tutorial should be easy to read and understand, which makes the organization and content of your write-up important. Think about writing this for your future self when you have to go back and pick up this language again.

To check whether you've made your report easy to read and understand, you may ask yourself the following questions:

• Organization
  • Is there a main page that indicates the main purpose of the page collection (e.g. this is a set of pages describing how a particular language implements standard programming language features)?
  • Does the main page have a title (e.g. Ying Li CS 333, Ying’s Explorations in R, Ying’s Notes in JS)?
  • On the main page, are there clearly organized links to supporting pages?
  • Does each supporting page have a title that indicates its role in the set of pages?

  Here is a recommended layout.

  	Ying Li CS333
  	|
  	|_Ying’s Explorations in R
  	| |
  	| |_P1
  	| |_P2
  	| |_...
  	|
  	|_Ying’s Notes in JS
  	| |
  	| |_P1
  	| |_P2
  	| |_...
  

• Content
  • Does the text describe what the language feature we are asking you to explain?
  • Does the code snippet illustrate the language feature that we are asking you to explain?
  • Does the text describe what aspects of the code snippet best illustrate the language feature we are asking you to explain?
  • Is the code snippet as short as possible?
  • If you worked with a partner, does the report title or text indicate that?
  • If you undertook any extensions, are they clearly described, including who worked on them.

---