hw4 guidelines

[mikeizbicki]

When you submit your final draft for hw4, you should adhere to the following guidelines. If you break n guidelines, you will have 5*(n-2) points deducted from your grade. For example, if you have 5 misspelled words and 1 other mistake, you will get an automatic -20 points on your submission. I highly recommend you get other students in the class to proof read your writeup for you before submitting.

Writing style guidelines:

1. Your first paragraph (and preferably your first sentence) needs to explain exactly what the reader will learn and why it's important. You will probably have to rewrite this paragraph several times to get something good.
2. Fluff is bad. If a sentence or word doesn't directly relate to the topic you describe within your first paragraph, you need to remove it. Most students are afraid to remove words because you want to demonstrate how much knowledge you have. But the purpose of this writeup is NOT to demonstrate your knowledge. The purpose is to make something useful.
3. Examples are the most important part of your writeup. You should spend about 80% of your time just making the examples as good as possible. Once you've done that, the writing that glues the examples together will be easy.
4. It's MUCH better to cover a small number of examples well than many examples poorly. Focus on quality, not quantity.
5. Use we/us instead of I/me. For example, Next, let's see what happens when we do XXX. (Remember that let's is a contraction for let us.)
6. It's okay to use you/your when describing the reader. For example, If you type XXX, the output should be YYY. Never use the word one to describe the reader. It's boring.
7. Your writeup should be in the present tense, not the past tense. For example, do NOT say We ran program XXX and the output was YYY; instead, say Now let's run XXX. You should get the output YYY.
8. You must have correct spelling and grammar.
9. You are allowed to break any of these rules if it makes your writeup easier to read.

Markdown formatting guidelines:

1. You must use backticks correctly to separate text that should be interpreted verbatim from normal text. For example, all code and excerpts from files must be in backticks. If you run something on the command line, it should be surrounded by three backticks and have a $ prompt symbol. The output should be contained within the same code block. For example,

   $ touch a
   $ touch b
   $ ls -a
   .       ..      a      b
   

2. Do NOT put a table of contents in any markdown files. This messes up certain types of post-processing. Instead, you should have a one or two sentence explanation about how your file is organized in your opening paragraph.

3. Break up your file into logical sections using the # markdown syntax, not the ---/=== syntax. Subsections are good. Every section must have at least one sentence inside of it.

4. Every sentence in your markdown file must be on a separate line. The markdown rendering engines will still display everything that's not separated by a blank line as one paragraph. This style of formatting is important for the results of git diff to be easy to read.

5. Code blocks should be as small as possible. Rarely should they be over 5 lines long. In particular, you should never include the entire contents of a cpp file in a code block. Only put the relevant pieces.

6. All your formatting must be done using pure markdown. In particular, you are not allowed to use any html in your markdown files. This will let

For an example of a correctly formatted file, see the README in the root of the repo. If you have any questions, please reply to this issue.