The readme.html File
Your readme.html file for each assignment should contain whatever information you think is necessary for a typical user to run your program and for a software maintainer (or grader!) to understand (and evaluate) your code.
Much of this information may be included on the original assignment write-up; you only have to fill in the parts we didn't provide for you already.
Information for the prospective user includes details on calling conventions, input and output data formats, limitations, bugs, and special features.
Explain both the negative aspects of your program (limitations, known bugs) and the positive aspects (extensions, special features).
If you don't include the former, we will assume you didn't realize the limitations were there.
If you don't include the latter, you may not get extra credit.
For the person who has to understand the insides of your code, you may need to describe your choice of modularization (abstractions), data structures, and algorithms. Be sure to explain anything you did that is likely to be different from what other students may have done, and justify any design decisions for which the rationale isn't immediately clear.
Your write-up should be clearly written, using full sentences and paragraphs. This writeup need not necessarily be long, but it is important.
All write-ups must be in plain text with Markdeep formatting using the template below. Other formats (e.g., Word or postscript) will not be accepted.
Template
The readme.html template (linked below) uses Dr. Morgan McGuire's Markdeep to format plaintext into nice looking HTML.
Below is a quote from the Markdeep website:
“Markdeep is a technology for writing plain text documents that will look good in any web browser. It supports diagrams, common styling conventions, and equations as extensions of Markdown syntax.
Markdeep is free and easy to use. It doesn't require a plugin or Internet connection. Your document never leaves your machine and there's nothing to install. Just start writing in Vi, Nodepad, Emacs, Visual Studio, Atom, or another editor! You don't have to export, compile, or otherwise process your document.
”
Features of the syntax are listed at https://casual-effects.com/markdeep/features.md.html.
Links to readme.html template:
- With Markdeep formatting: https://gfx.cse.taylor.edu/courses/cos382/assignments/readme/readme.html
- Unformatted version: https://gfx.cse.taylor.edu/courses/cos382/assignments/readme/readme.html?noformat.