There are some common mistakes students do the first time they try to write a report describing the project work they've done. In this lecture some of those mistakes are pointed out so you can avoid doing them yourself. But first some important theory to know before you start writing your report.
Most reports are associated with a project, so you must have a good understanding of what a project is before you write a report on one. Wikipedia's Project pageopen in new window has a long definition of the term, but let us only focus on projects where the goal is to implement some software. A project is always about a problem that should be solved, and the solution (in this case the software) you create should solve that problem.
The goal with the software you create is to get people to use it (no point in creating something no one will use). Why would they use it? Because it will help them in some way. So the first thing you should decide in a project work is: What is the problem people are having that we will try to solve in this project? Examples of problems are:
Crossing the road is dangerous.
Waiting (in line, at a bus stop, at the traffic lights, etc.) is boring AND a waste of time (two problems in one).
Leaving the children home alone is dangerous (parents are worried about both the house and their children).
Communicating with someone not speaking your language is hard.
Remembering when Arsenal plays their next game is hard, and it changes after each game.
Contacting all players in a hockey team (to notify them of cancelled matches, changed practice hours, etc.) is hard/time consuming.
Knowing what is cheap and what is expensive in a grocery store is hard.
If you can't come up with a problem on your own, simply ask a friend or a company about problems they're having, and then you can try to solve that problem as your project.
When you have identified the problem to solve, you need to analyze the problem in depth to get a better understanding of it, so you know things like:
Who are having the problem?
What is characteristic of those having the problem? E.g.:
Are they rich?
Do they live in big cities?
Are they old?
Do they all have driver licenses?
How much time are they willing to invest to solve the problem? (e.g. 15 minutes to learn how to use a new app?)
Etc.
When are they having the problem?
How does the problem impact the rest of their lives?
Etc.
Analyzing the problem in depth could be a big project itself taking many months, but let us keep things minimal here (you don't have time to do a proper analyze of the project in depth for the project you do in school) and move on.
When you have a good understanding of the problem, you need to come up with a solution to the problem. What the solution looks like do of course depends on what the problem is, but in our case the solution will always involve the creation of software. For example, if the problem is My children has grown up and now I have a lot of small clothes no one in the family can use, then maybe the solution could be to create a website where people can sell their clothes online to others.
Often you don't only come up with one solution, but many different solutions (coming up with different solutions could be a project itself taking many months), and then you continue to work with the solution you think is the most promising one. When you do, you need to be sure that the people having the problem really think that the solution you pick is a good solution they are willing to use (optimally willing to pay money for 🤑). You can compare your solution to existing solutions to see if your solution seems to be better. For example, parents might now throw/give away their children clothes for free now, but with your solution they would get some money for the clothes, making them prefer your solution. Making a survey and asking the people having the problem if they think your solution is a good idea is of course a very smart thing to do.
When you have decided which solution to go with, you need to realize it (in the previous example implement the website). When you're done realizing the solution, we'll for simplicity consider the project to be over. Real projects could however continue after this. For example, the following could also be part of the project:
Delivering the solution to a customer.
Running the solution for a customer.
Maintaining the solution for a customer.
Add new functionality to the solution for a customer.
Now that you have a basic understanding of what a project is, let's take a look at how we can write a report about one.
Reports describing projects tends to be quite long. Therefore we divide them into chapters, making them a bit more structured. But which chapters should we have? In which order should they be? There's no single correct answer to this, but let's go through an example of a good structure for a report.
The first chapter in the report should introduce the reader to the project. The reader does so far not know anything about your project, so the first thing you need to explain to the reader is which problem you try to solve and how you intend to solve it.
In this chapter you can think of the reader as an investor with a lot of money, and your goal is to convince the investor that the problem is a serious problem worth solving, and that your solution solves the problem in an excellent way. If you manage to convince the investor of this, she might be willing to invest some money in your project, and you get the money you need to start working on the project and to build the solution.
In our case the solution is a website, so we need to tell the reader what problem the users of the website are having and then explain how they solve that problem by using the website. A UML use-case diagram is an excellent tool to visualize what the user will be able to do on the website.
Keep it simple!
Investors are not technical people (just rich and stupid bastards 😉), so avoid using technical terms. Anyone reading your report should be able to understand all the text in the Introduction chapter, even your own grandpa who doesn't even know how to turn off the radio.
So, you have decided on a solution and you've got the money you need to build it from an investor? Great, now we just need to figure out the technical details of how to build the solution. The solution is usually quite complex, so dividing the solution into multiple chapters is usually a good idea, but if the solution is small and simple, a single chapter describing the solution can be enough.
In our case, the solution is a website, so this chapter could be about giving an overview of how we will implement the website. In our case we could explain that a user will use her web browser on her computer to communicate with our web application running on our server, and our server in turn will communicate with our database that runs on yet another server.
In our case the solution consists of two components we create ourselves:
The web application
The database
We have a lot to say about these, but that will be implementation details, and those are probably better described in chapters dedicated to describe these in detail, so this chapter is just about the architecture of the solution (an overview of the solution). This way, readers who don't know much about programming should still be able to read and understand most parts of this chapters.
Tips!
In our case we describe the architecture of our solution in this chapter, so maybe Architecture is a more accurate chapter name than Solution? It's your report, you decide!
Keep it simple!
In the Solution chapter you have to get a little bit more technical compared to the Introduction chapter, but try to keep it simple (avoid mentioning technical implementation details unless it makes sense to mention them here) so most readers can read the chapter and understand the solution overall without being technical experts. Your grandpa should be able to understand most of what you've written, even though he doesn't know where the any key isopen in new window.
We can use a separate chapter to describe the database component in our solution, so in this chapter we describe everything there is to know about the database, such as:
What database do we use (MySQL? SQLite?, MariaDB? Etc.)
What tables do we have in the database?
What columns do we have in the tables?
What constraints do we have in our database?
...
Tips!
In this chapter you can expect the reader to know a lot about databases, so don't expect your grandpa to understand much of what you write here. This chapter will primarily be read by other developers working on the project to learn how they should use the database, and by quality assurance people (your boss, your team's quality assurance member, your customer's quality assurance checker, etc.) to verify that your solution has been implemented in a good way.
Remember!
This chapter is about the database only, so no need to mention anything about the web application in this chapter.
We can use a separate chapter to describe the web application component in our solution, so in this chapter we describe everything there is to know about the web application, such as:
Which framework is the web application implemented in?
How is the source code structured?
How is authentication and authorization handled?
How is information about the clients remembered? E.g. cookies, sessions, tokens, etc.
Which security vulnerabilities has been thought of and is protected against?
Which libraries is the web application using?
...
Tips!
In this chapter you can expect the reader to know a lot about how web applications work, so don't expect your grandpa to understand much of what you write here. This chapter will primarily be read by other developers working on the project to learn how they should add new features to the web application, and by quality assurance people (your boss, your team's quality assurance member, your customer's quality assurance checker, etc.) to verify that your solution has been implemented in a good way.
Remember!
This chapter is about the web application only, so no need to describe implementation details of the database. The only thing you need to mention about the database in this chapter is how you communicate with it/connect to it.
Add whichever other chapters you want that make sense to have. Maybe a chapter describing the website's graphical user interface is good to have? Or maybe designing the graphical user interface is an entire project on its own? Maybe the solution also includes a smartphone app? Then having a chapter explaining the implementation of that app would be good? Or maybe the smartphone app should be described in a separate report? Maybe our solution also includes special days people can come to a house and leave the clothes they want to sell there, and then others can come to the house and buy them? Then a chapter explaining how this works would be good, etc.
When you write a report you must always remember that you write it for the readers. Each time you hesitate over something, such as:
Which chapters do I need?
In which chapter should I write this?
Do I need a figure to explain this?
Have I explained this good enough now?
Always think of the reader. Pretend you are a very stupid reader of the report, and that you don't know anything about the project. Then try to answer your question, and then go with the answer you come up with.
Your opinion about the report doesn't matter
It doesn't matter whether you think the report is good or bad, what's important is what the readers think of your report, since they are the ones who will read it. To make them think the report is good, you often need to do more work on it than you initially think is necessary, because you know YOUR project work by heart, but the reader doesn't know anything about it, so you need to explain more things than you think.
If you write something that can be interpreted in different ways, readers have no idea which way that is the correct interpretation, since they don't have anyone to ask for clarification. So, when it comes to written text, it's very important to be explicit about what you mean, so there's no way for readers to interpret the text in different ways.
Example
Let's take a look at an example from a report describing how a blog on an Android app works:
It doesn't work to create empty blogposts.
The problems with that wording are:
There's no explanation of what doesn't work means. The app doesn't contain that functionality at all? Or the app crashes when that functionality is used? Or does nothing happen when one click on the create-button? Or is an error message shown to the user?
There's no explanation of what empty means. Missing all of title, content and date? Or just missing title? Or what?
As you see, sentences in a report that are that vague are more confusing than helpful to the reader!
Let's take a look at a better worded sentence:
When creating a new blogpost with an empty content, an error message is shown to the user indicating that new blogposts must have some content.
This is much better! Everyone reading this sentence will get the very same understanding of how the app works. But most likely, you will have more validation rules than just that one, and you need to describe all of them. Then you should not describe each of them in separate sentences like that, but rather show them in a list, or a table, as in the example below.
When creating a new blogposts, the following validation rules are applied:
The content of the blogpost must not be empty
The content of the blogpost must at most consist of 1000 characters
The title of the blogpost must consist of at least 5 characters
The title of the blogpost must at most consist of 75 characters
The publication date can not be set to a date in the past
If some of the rules are not followed, they will be shown as error messages to the user.
This is a very good way of describing how it works;
Lists are used, so it's easy to see where all the validation rules are specified, and to count how many they are, etc.
It's very easy to add more validation rules in the future: just add a rule to the list
Even if your app only has a single validation rule, displaying that one in a list is still a very good idea, because it gives the report a very good structure, and it's very easy to add more validation rules to the report in the future.
Example
Another example from a report on a website:
The client communicates with the server, and then it crashes.
What crashes? The client? The server? The network? Or everything? Students love overusing the word it, but readers hate, because they often don't know what it refers to. It is much better to be explicit:
The client communicates with the server, and then the client crashes.
This is much better, now all readers gets the understanding that it's the client that crashes. But then in the sentence is still ambiguous. WHEN is then?
then = Directly after the request has been sent?
then = While waiting for the response?
then = When the response is being received?
then = After the response has been received?
Different readers will make different guesses here, and get different understandings. It's much better to be explicit than vague, for example:
The client sends an HTTP request to the server, and when the client receives the HTTP response from the server the client crashes.
This sentence is explicit all the way, so it's very easy to read and understand, and everybody gets the same understanding from it.