How to write a design document

Transcription

1 How to write a design document Øystein Dale oystedal@ifi.uio.no February 23, 2015

2 First off Writing a design document is something new for most of you. Before: Read mandatory assignment/exam description, then implement. Now: Read project description, think, design, implement.

3 Why do we write a design anyway? The design gives you an opportunity to do research. What is the problem? Why do we want to solve this particular problem at all? How do we solve it? How do we solve it on x86 hardware? Use the time you have available to find out all you need to know in order to implement. That will make the implementation a lot easier for you.

4 Who is the audience? The group teachers? You? Your partner? Imagine someone who has a bachelor in CS (someone like yourself), but hasn t taken an OS course. This should be your audience.

5 Important considerations for the design The design is meant to solve a problem. The design is the solution to the problem. The implementation is a proof that the design is correct. Someone else should be able to implement your design. Enough details, but not too much.

6 Design requirements The project description defines what the implementation must be able to do. How it does it, and how well it does it is up to you.

7 Have a clear outline Structure is key. Easy to see that you ve mentioned all you want to. Easy to fill in text as you go. Explain concepts before you use them in the design.

8 Starting off with a short introduction At most a few short paragraphs, no details or discussion. Possible questions you may answer: What is the goal of this design document? Why are we making this? What is being designed? The goal of this document is to specify the design of a bootloader for a small kernel. (etc.)

9 Example background for the bootloader project How do we go from a kernel on a USB stick to a running kernel on a machine? This should spawn a number of questions: What happens when we turn on the computer? What does the BIOS do for us? What do we have to do ourselves? How do we load the kernel from the USB drive? What happens if......

10 The questions you come up with are important. They may uncover issues that we expect you to address in the design. We will not give you hints about this unless you discuss it in the design.

11 Discussing multiple options In the coming projects, you ll have more freedom to discuss how to do certain things. Consider a few options, discuss the advantages and disadvantages of each one Does a certain option imply any assumptions? Does a certain option impose any limitations? Choose one, and give a reason for choosing it.

12 Illustrations Every good design should have illustrations, even if we don t ask you to make one. Important: Explain them with text as well. Be careful, a bad illustration leaves the reader confused. Even more confused if it s poorly explained.

13 Additional information Some information may not be required in the design document, but is very useful to have as a reference. Feel free to include this in the document, if you have space and time left. Examples for P1 would be: Addressing with segments (most people wouldn t know this from before) Writing to screen (several options, pick one) Additional information about INT 13h Anything else you feel would be useful to know when implementing.

14 Some common issues We don t know what to design Look at the project description, the slides from the project presentation, and the slides from the lectures. We have to implement it first to have a correct design If you think through your design, then you can argue whether it is correct or not. You have to use your brain for this part. You risk knowing what the solution is, but not knowing why it works. If all else fails: Ask us. We might give you some pointers. Also: The Intel manual is a nice read. See the tips & tricks page. We still don t know the solution to a problem Explain what the problem is, and ackowledge that you don t know the solution.

15 Conclusion Writing a design is not supposed to be the easy part of this course. Neither is the implementation. You learn a lot more if you understand the problem and the solution before you implement it. The design is meant to help you when you implement. Making a good design will give you a head start on the implementation. Please start on Wednesday or Thursday, not on Monday. #inf3151 on irc.ifi.uio.no