Writing a report

Question

Hello all,

Since some time I've been investigating more time into profiling things better, really think about how to do a thing and why. Now I'm going to start a new project, where I will be writing a report about.

The report will be about anything what I wrote in the project, why, and I'll be investigating some things and do particular research about them. I've seen some reports, such as game programming in Haskell using FRP. However, after reading several reports they all seem to be build different.

I have a few questions about writing a report:

1] What are the things I really should include, and what are the things I really shouldn't include?

2] Is it useful to include graphs about different methods/approaches to a several problem, where you only included one into your project, to show WHY you didn't include the other methods. Or should I just explain the method/approach used into the project.

3] Should I only be writing the report after I've completed the project, or should I also write pages about what I expect, how I'm going to build the software?

Thanks,

William van Doorn

Answer 1

Your report should include information that supports your thesis. Begin with a proposition, or group of related propositions, and your report will either prove or disprove those propositions. For example: "Haskell is a compelling and powerful language for creating games," or "Haskell is not an all-around good choice for game programming," or "Haskell makes an excellent companion to C++ for creating games." So, start with a central argument, figure out how you will prove or disprove it based on your experience and prove that conclusions with methodical, logical steps and evidence to support them. Don't include anything else.

Graphs are useful when they present your data in a way that makes it easier to understand than written words. Remember the old phrase, "a picture is worth a thousand words?" Use that as your guiding principle. Don't include a graph for its own sake, but if you are writing a great deal to explain a complex set of data, think about how it could be easily visualized with a graph. Don't look for excuses to include them just because they look cool.

The answer to your third question is entirely dependent on why you are writing the report in the first place. Is the point of the report to keep high-level decision makers informed about how you plan to spend your year of programming? Is is to help your colleagues avoid making a number of mistakes while undertaking similar work? Decide why you are writing the report and then you will know if it should be written before or after the fact.

Answer 2

Rather a wide-ranging and vague question, so here's a vague and potentially wide-ranging answer.

Table of Contents for Any Report:

1. Summary
2. Problem Statement
3. Method
4. Results
5. Conclusions
6. Further Work

Feel free to move these chapters around if you want to, but include them all.

Now to your questions:

1) Omit everything which isn't essential. If you can strike out a word or sentence or paragraph or section or chapter which leaves your reader with the same understanding as if you left it in, then strike it out.

2) Gosh yes, pictures of all sorts are essential: they lighten the tone and appearance of technical reports, they are the right way to express some types of idea and concept, and they force the author to think very hard about their subject matter.

3) No, write as much of the report in advance as you possibly can. Seriously ! It's a bit like test-driven development, if you can write your results first (ie your tests) then do the work and get the data to support your results you've done a good job. This will also help you to avoid scope creep during the work -- if an interesting avenue which appears doesn't help to deliver the results you plan, don't follow it.

Good luck.