speaker Multimusen

How to write about code

March 16th, 2015 by

In most projects at the Multimedia Communication and Design programme you will be asked to write an academic report following the academic standards from Harward.

Since interaction and code has a weight of some 25% at the first and second semester and around 30% at the third semester it is natural to expect a similar weight in a report. So if you’re supposed to write say 15 pages then roughly a quarter of the pages would be ok.

Strategy I: The Silo
Now there are certain strategies you can follow. Old school reports tended to have divisions for each subject. So the students would write something for the business, communication, design and interaction teachers.

Doing so is not bad at all. But the report will look a bit like four silos. And if you divide the stuff there is a tendency to focus only on the subject at hand.

Then you may forget, at one subject is closely linked to another subject. Ideas from design will affect the code – and vice versa.

Strategy II: The Cross-subject Report
Another strategy is to see how the subjects are connected. Perhaps your communication leads to a persona.  She’s 25 years old and just loves webpages with pink animations of running horses.

In that case you have ideas for the design. There will be horses. And the color pink will play an important role in your design. One way or another you will have to animate the horses.

This again leads to the code that you have to write. Perhaps you’ll use the Jquery plug-in Spritely.

So you draw a spritesheet in Photoshop. Yep, that’s design. And then you implement some animation code on the website. That’s interaction. Perhaps you made a sketch too. And so you have something, that could turn into interesting pages in the report. Here’s the code:

$('#pinkHorses').sprite({fps: 12, no_of_frames: 7});

You may imagine the pink horses and so in your mind …

In one illustration you could have your sketch, the code needed and the result in a browser. And here you cover more than one subject in an interesting way.

Don’t tell it – show it!
A sound creative writing principle is “don’t tell – show”. Let your report demonstrate how you developed your idea. And how you implemented the code in the end.

Perhaps the censor does not know anything about code. So you have to explain what your code does. It’s a bit like expaining the rules of a game to a younger sister or brother.

In the codesample above you could explain, that:

  • The sprint was made on a sunny tuesday in march.
  • Tell that you have importet the script pinkHorses.js.
  • $(‘#pinkHorses’) is Jquery. It will select the tag with the id pinkHorses.
  • In the CSS you have styled the tag, so that you only see one of the horses in the stylesheet.
  • Basicly the plugin will move the background with 12 frames per second. The result is the illusion of moving pink horses.
  • You could discuss whether 12 fps is satisfying or not.
  • You could countinue to animation principles from the Disney studios from “Steam Boat Willie” and on.
  • And how about the sounds of the running horses … and the cute Jquery controlling the sounds.
  • By thine own ingenium invent more …

Now you have a cross-subject line from business, communication and design to an interaction code sample.

 Third party code
Jquery and a Jquery plug-in is third party code. Since you did not invent either Jquery or the Spritely plug-in you have to give the sources in your report.

In the bread text of your report you may give the url to Spritely in a footnote. Do it like this:

http://spritely.net/documentation/ (visited 16.3. 2015)

At the end of the report you’ll have a list of sources. Here you must write all thirdparty code used. If possible sorted by author – or at least by the name of the code library.

Harward Academic Standards
Here is the link to the academic standards that we use at the Aarhus Business Academy. Use them because we expect you to do so.

You link to a website like this:

NHS Evidence, 2003. National Library of Guidelines. [online] Available at: <http://www.library.nhs.uk/guidelinesFinder> [Accessed 10 October 2009].

So how would you write, that Jquery and Spritely was used in your academic report?

Remember that a PDF file can handle hyperlinks. So use links in your report – and link to your product on the frontpage too.

Conclusion
When you write about code you have to demonstrate your powers as a coder. Don’t explain what HTML and CSS is. It’s far better to explain why your markup looks as it does.

Perhaps you wrote some cool class in PHP, that can generate the HTML for the user. Or functions you can reuse for other animations. How are these classes and functions connected to your overall design ideas, why do the look the way they do … and could you have acheived the same thing in a better way?

To be honest your teacher and censor love discussions and usertests. Well, this may be off topic. But even the coolest code is worth nothing if your user cannot use your product.

To sum up:

  • Show how your code works.
  • Try to demonstrate the path from the rough sketch to the finished code.
  • Give credits to the authors of ANY third party plugins.
  • Use the Harward System.