Writing a great design document

Rules#

• Your design document must be a maximum of 1000 words (not counting references, or things like table symbols, etc.)
• Your design document must be a markdown file called report.md.
• Any text or images reproduced from other sources (e.g., Wikipedia) should be clearly quoted and cited in the references section in your statement of originality. Reproducing text without citation is considered plagiarism.

This document is to help you write great design documents for COMP2300/6300/ENGN2219. It is aimed at all assessment items. This is not a step-by-step guide (or template) for getting the “right answer” for the DD part of the assignment. It is a guide for writing clearly, and communicating the important information.

What, How and Why#

The assignment specifications ask you to answer these questions in your design document.

• what your design is (and how it meets the assignment specification)
• how you accomplished it
• why your design choices were appropriate for the task

There are many ways to structure your document to address these questions. You may choose to use these questions as headings in your design document. You could answer the what question in one or two sentences and then answer how and why for each important part of your program. As long as this critical information is in your design document, you will have met the specification.

Style Guide#

The first thing the reader sees is the style of your document, both in terms of layout, and expression. Style is important, get it right:

• Use headings and sections to arrange your work.
• Use diagrams/images if it helps to describe your design.
• Correct spelling and grammar is essential.
• Writing style should be clear and concise. All important aspects must be explained without unnecessary low-level descriptions (eg. line by line code, gate level descriptions).
• Your design document should be in correct markdown syntax (i.e., links and images should work when viewed in “markdown preview”, code snippets should appear as code, not text).

For help with markdown syntax, see the syntax section below.

Structure#

You can use whatever structure you want, but a good place to start would be:

• Design: What have you created? What do you expect your program / circuits to do? It should be crystal clear to the assessor what you have done and what is expected. If they have to read your code / look at your circuits to find out, your explanation isn’t good enough. The first sentence of your design document should summarise what you have done.
• Implementation: How have you implemented your design? This is your chance to explain control flow and structure behind your program or high level circuit design. Provide enough detail such that the reader could reproduce your implementation without seeing your code. But make sure you don’t provide “unnecessary low level detail” (see below).
• Analysis: Why is your implementation correct and appropriate for your task? Why should we consider your solution to be successful? Why did you choose this design and implementation approach? Make sure you analyse what your final design does well and not-so-well, don’t just provide a journal of your programming / designing process.

Finding a balance between high- and low-level explanations.#

You need to explain your implementation in enough detail so that the reader could implement it without seeing your code. For example, in the microbit assignment, just writing “I generated an LED pattern” is not sufficient: it is too high-level. You need to explain precisely what the pattern is, and how your program generates it. For the Digital assignment, tt is not sufficient to say, “I extended the CPU to support XOR”. Where did you add this extension (register file, ALU, control unit, multiple places)? What is the corresponding machine code you defined for it?

Similarly, you should avoid “low-level details”. E.g., if you explain how to do basic arithmetic and which registers are used (“r1 (array index) and r2 (element size) are multiplied using the mul instruction”), this is too low level. You could more clearly write “the memory offset is calculated from the array index and element size (16 bytes)”. Writing a line-by-line explanation of your code, or a gate by gate explanation of your circuit, doesn’t help answer the “what, how, why” questions.

A sophisticated submission would express:

• how control flow and program structure is required to create your program
  • e.g., “I used a for loop to iterate through my pattern, in every iteration, I load part of the pattern from the array stored in memory.”
• how circuit flow and logic is used to realise your overall design
  • e.g., “I used a feedback loop composed of a register and an incrementer to create the program counter for my CPU. I have also included a multiplexer in the feedback loop which is connected to the RAM and controlled by a 1-bit signal from the control unit to allow for branching operations.” These explanations clearly describe what is going on, but do not go through each line of the code / gate of the circuit to do so.

Analysing and Evaluating your design#

When you are explaining your design, you need to motivate and explain the choices you have made. We need to know “what” your submission does, and “how”, and also “why” this approach works. This means you need to analyse your design and evaluate it in terms of what you set out to create.

For example,

• if you chose to use an array to store data, rather than using static variables
• if you chose to add the flag register to the top level schematic, rather than in the register file

We need to know why you made that decision, and what this decision means in terms of your design’s functionality. When you explain this, make sure you back up your explanation with facts and evidence to form valid arguments.

Your analysis should absolutely not explain your code line-by-line or your circuit gate-by-gate. It should definitely be focussed on higher level design choices.

Clear and concise communication#

Clear and concise communication and expression are part of the marking criteria. If your communication is unclear, we cannot be sure of what you really understand about how your design works.

If you explained some of your code / circuit as follows:

This function / circuit is very important.

We might wonder why you have drawn this conclusion. What does “important” mean? Why is it more important than other functions / circuits?

A better approach would give a precise, but concise, explanation of the role of this function / circuit.

The additive_mixer function is important to this design, because it sums the current samples while ensuring that the output does not overflow.

The input_muxer circuit is important to this design, because it calculates / computes the desired immediate value to be used by the ALU.

This approach says which function / circuit is important, what it is important for, and why.

Examples#

We have some examples of design documents from previous versions of COMP2300 kindly donated by tutors.

Note that the requirements for design documents and the assignments were different, but these give you some clues about expected style, and the “level” of explanations.

Markdown Syntax#

Your design document is in markdown format. Markdown is an easy-to-read and easy-to-write plain text format that is designed to be easily converted into documents in HTML format. You can read about the basic syntax here (link).

Markdown supports all kinds of formatting, here’s some examples (and links to documentation) to help you get started:

• headings (we prefer the hash # symbol syntax)
• bold and italic text
• lists
• code (inline and blocks)

We expect you to use correct markdown syntax when creating your design document so that when converted to HTML it looks great.

Pictures, graphs & diagrams#

Pictures graphs & diagrams are encouraged, but should be used to support your design document text. In particular, your text should refer to them explicitly (e.g., “Figure 1 shows a plot of the first note and its envelope shape.”).

To include a picture (e.g., image-1.png) in your design document:

1. commit and push image-1.png to the assets folder in your assignment repository (the assets folder is provided to store pictures for the design doc neatly).
2. use the markdown image syntax (link), e.g., ![Description of the image](assets/image-1.png)
3. when done correctly, the image should show up in “Markdown Preview” in VSCode, and when you view your design document online.

Images of code are absolutely unacceptable in your design doc. Include any code snippet as text in your document as shown below. Do not include screenshots or photos of your code.

Circuit Screenshots#

Even though you should not explain your circuit gate-by-gate, this does not mean that you cannot include circuit screenshots. However, you should only include a circuit if you have a good reason to, which might include:

• The circuit is from a “previous attempt” at writing your CPU that you want to discuss. Because it is from a previous attempt it is not in the circuit part of your submission so including it in the report makes sense.
• You want to show an alternative implementation you tried (and are going to explain why you made a different choice).

If you do include a circuit screenshot, do not include it as a low-resolution screenshot of your circuit. It must be clear and easy to read, even when zoomed in.

Code snippets#

In general, code snippets aren’t always necessary as the reader will have access to all of your code already. You should only include a code snippet if you have a good reason to explain some code. Good reasons might include:

• It’s code from a “previous version” of your program that you want to discuss.
• It’s an “alternative implementation” used to demonstrate an improvement in your program.

If you do include code, make sure you use either inline or block code markdown syntax

Viewing your design document#

So you’re writing in markdown, but how can you view a nice “rendered” version of your document? Quite easily as it turns out!

• If you are writing your design document in Visual Studio Code, you can access a “preview” using the Markdown: Open Preview command. This will let you see that your syntax is correct and that your images are in the right place.

• Once you have committed and pushed your design doc to GitLab, try viewing it on the gitlab website. Again you will see the “processed” version of your markdown document including images.

• If you want to get the final version of your design doc, one of the Gitlab CI jobs generates a self-contained PDF file of your document and uploads it as an artifact attached to that job. Have a look at your CI jobs to download it.

Help on Academic Writing, Editing, and Style#

If you need help with your writing, have a look at the Academic Skills Writing Centre.

This centre provides some great resources, for everybody at ANU (even lecturers!). I particularly like their hints for Editing and Polishing work:

• ANU Advice on Editing and Polishing your work
• Syle and Authorial Voice
• Flow
• Cohesion