Implementor's Notes

You've probably heard many times that it is important to document what you do. Well, that's not just for work in industry. Documentation of your projects helps both you and the course staff. However, it's a very specific type of documentation we want in this course: implementor's notes.

What Belongs In Implementor's Notes?

What are implementor's notes? Well, they are not a user manual, neither are they comments in your code. They are simply all the things that another person -- or you a month later -- would need to understand how you implemented the project. Think about what you would need to know if you had to modify, debug, or enhance your project code a month later. You generally don't need a user manual for a project because the project handout usually includes that, and there's no need to repeat what's been said in the course materials. However, implementor's notes also are quite different from comments in code. Comments in code are about what is happening around that position in the code; they're inherently local. Implementor's notes should be global -- giving the big picture. They should explain design choices, such as what algorithm you selected to use and why that algorithm instead of any other obvious choice. They also should make it clear how you decomposed the problem to implement a solution and why you did it that way.

However, implementor's notes also should give some indication of how well the implementation works. If there are problems you can't debug, they ought to be discussed in the implementor's notes. There's an old saying in the Unix world that a documented bug is a feature. Well, that's (mostly) a joke, but a documented bug sure is a lot better than one that comes as a total surprise... especially when course staff are grading your project. I'm actually such a strong believer in implementor's notes that I will actually count any documented error/problem in a project as being half right. I'll do that even to the extreme point of accepting a project that is simply an implementor's notes file saying "I didn't get around to doing this project, so it doesn't work" as getting half credit. (Clearly, nobody should ever get less than 50% credit on any project in this course!)

How Are They Formatted?

I used to require simple HTML mark-up because a lot of students had never done that and every computer engineer should have to do that at least once in their undergraduate career. However, the same statement is true of writing a technical paper to comply with publishing guidelines from professional societies like ACM and IEEE.

For EE480 this semester, I will not be too picky about the formatting, but you should approximately comply with the formatting of the templates from either the above ACM or IEEE site. Both give templates for word and Latex; Latex is more often required in the computer engineering field, but for your implementor's notes you may use either. All you need to submit is the PDF generated in rough compliance with one of these formats: i.e., US letter-sized 2-column format (possibly with figures spanning both columns) and content looking similar to the template examples. Real conference and journal publications will often reject a paper without review for such minor issues as having the column width wrong by a few mm, but for this class, it's ok if it looks about right and it can be missing any portions that are not need to convey the ideas required for Implementor's Notes, such as references or author biographies.

If you should need to include code in your document (which you probably will), please distinguish it by using a fixed-spacing font like Courier. For example, Verliog code ought to be rendered in a fixed-width font even if it isn't big enough to make into a figure -- like always@(posedge clk) is here.

How Big Should This Document Be?

Large enough -- and no larger. I would expect most projects to have Implementor's Notes that easily fit on a single page. However, if you need to, you may use more pages up to a total of 10. Why 10? That's a typical size limit for a complete technical paper... and your Implementor's Notes should not be a complete technical paper.

A Simple Example

A simple example of what Implementor's Notes should look like is this PDF file. I have also posted the Latex source file which creates that PDF -- using pdflatex with the ACM format files. That example was for my sample solution to the project 8-bit Signed Saturation Adder.


EE480 Advanced Computer Architecture.