Writing a great design document

Here’s the TL;DR

  • you document should answer the questions “what”, “how”, and “why”; after reading it, your tutor should understand not just what you did, but how it works, and why you did it that way
  • this is a formal piece of academic writing—treat it professionally and with respect (and don’t hack something together at the last minute)
  • do not explain your code line-by-line
  • Read through your design document on Gitlab after you have submitted it to make sure it looks how you expected.

This document is to help you write great design documents for COMP2300. 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. Rather its a guide for writing clearly, and communicating the important information.

Style Guide:

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

  • Use A4 page size
  • Use a 12-point standard font (e.g., Times New Roman, or similar)
  • Use margins that are 10mm-25.4mm (i.e., standard margin sizes)
  • Use a high-quality document editor (such as Microsoft Word—available to all ANU students online) or LaTeX to prepare your design document.
  • Include a title (size 14, bold is sufficient to indicate this, don’t use a title page).
  • Include your full name and university ID (size 12).
  • Use headings and sections to arrange your work.
  • Use diagrams/images if it helps to describe your design (refer to your diagram in the text).
  • Correct spelling and grammar is essential.
  • Writing style should be concise and clear. All important aspects must be explained without unnecessary low-level descriptions.

Rules (breaking these results in deductions)

  • The main content of your design document must be a maximum of two A4 pages. (This content includes images etc. if they are not in the appendix.)
  • You may have an appendix or references on extra pages. You must use a heading that says “appendix”, or “references” to indicate these sections.
  • Your design document must be a real pdf called design-document.pdf.
  • Any text or images reproduced from other sources (e.g., Wikipedia) should be clearly quoted and cited in your references section. Reproducing text without citation is considered plagiarism.

Marking Criteria

The marking criteria are the same for each design document.

  • Sophistication of your design and how it meets the assignment specification.
  • Sophistication of your implementation in assembly language.
  • Sophistication of your analysis and evaluation of why your implementation is correct and appropriate for your design.
  • Demonstration of understanding of the course learning outcomes that apply to this assignment.
  • Clarity of communication and expression.

Sample 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 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 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. 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 design? 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 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.

In assignment 1 for example, just writing “I generated a sine wave” is not sufficient—this is too high-level. You need to explain precisely what a sine wave is, and how your program accomplishes this kind of wave shape.

Similarly, you should avoid “low-level details”. In general, discussing how you have used different registers (e.g., “r1 is used to store the frequency, r2 is used to store the maximum amplitude, r3 is used to count wavelengths”) is too low-level, this information could be better expressed as “my program calculates the wave parameters within each iteration of the main function”. Similarly, if you explain how to do basic arithmetic (e.g., “r1 (array index) and r2 (element size) are multiplied using the mul instruction”), this is too low level. Naturally, the mul instruction is used to multiply numbers, so this doesn’t add further information, you could write “the memory offset is calculated from the array index and element size (16 bytes)”.

A more sophisticated submission would express how control flow and program structure is required to create a waveshape: e.g., “I used a for loop to iterate through my wave shape, in every iteration, I load the sample from the wave table stored in memory.” This explanation clearly describes what is going on, but does not go through each line of the code 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 program 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 using static variables, we need to know why you made that decision, and what this decision means in terms of your program’s functionality. When you explain this, make sure you back up your explanation with facts and evidence to form valid arguments.

Sometimes your analysis could refer to previous or alternative attempts but only if this suppots an argument about why your program is successful.

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

Learning to evaluate and analyse programs well is a hard but crucial skill you need to develop throughout your degree.

How we evaluate a design document

Your design document is evaluated holistically. That means we look at the whole thing and choose a mark that represents your level of achievement. We take into account that part-2 is the hardest part of an assignment and so you must earn marks by providing a good document that explains what you have done. An unacceptable design document is likely to earn zero marks.

To help moderate our grades, we look at a number of aspects of your design document. Note that these are examples of aspects of an assignment that can be discussed throughout, there is not necessarily equal weight given to each one:

  • Design:
    • What does the program do? What is the overall goal? Is this clearly explained in the opening of the document?
    • How sophisticated or difficult is this design?
    • Does the design meet the assignment spec?
    • Does the document focus on the aspects of the program in the assignment spec?
  • Implementation:
    • Is the program structure sophisticated or simplistic?
    • Does the program apply logical / mathematical procedures that are sophisticated and are these explained clearly?
    • Does the document clearly explain the control flow, program structure, and use of memory?
    • Are these explanations clear and concise or are they too high- or low-level?
  • Analysis:
    • Is it clear from the document why design decisions were made in this program?
    • Does the document describe why this approach might be better than others?
    • Does the document reflect on the outcome of this implementation?

This isn’t a checklist—you can’t point to anything on this page and say “I did X, so I should receive full marks”. However, this gives some indication of how we moderate marks across 350+ design documents.

There are also many things you might want to put in your DD that are not mentioned here, and that’s fine. This page is aiming to guide you if you’re struggling with this document and it should be considered a starting point and/or a sanity check.

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.”). Images should be either in vector format or a high enough resolution so that they are clear.

Do not include images of code.

Code snippets

In general, code snippets are unnecessary as tutors have access to all of your code already. You should only include a code snippet if you have a good reason to, which might include:

  • The code is from a “previous version” of your program that you want to discuss. Because it is not included in your submission, putting it in the report makes sense.

  • You want to show an alternative implementation. For example, you read & wrote some values to memory for robustness but you could also (in this case) have kept everything in the higher registers (for performance).

In these two cases including the code snippet would allow you to evaluate your submission in a more sophisticated way; definitely worthwhile.

Screenshots or photos of your screen are absolutely unacceptable representations of your code. Include any code snippet as text in your document in a monospace font.

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 as follows:

This function is very important.

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

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

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

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

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:

Updated:    08 Jul 2020 / Responsible Officer:    Head of School / Page Contact:    Charles Martin