Lecture 3: Writing the Project Documentation Part I

Topics that will be coveredStructuring ReportsWriting AbstractsReferencing MaterialPresenting DataDocumenting SoftwareCommenting ProgramsWriting User Guides

Why to document your project? And why it is important?Sometimes, a graduation project is not

accompanied with a software, then the documentation would be the evidence of the project.

Dissemination of ideas and results

Good work (software for example) could be ruined by a poor report, that doesn’t justify your practical work right.

Writing and Structuring ReportsConsiderations

What is the purpose of the report? Best Mark Work Dissemination Provide Literature Review Inspiring others Fulfill Requirements of your course

Who is going to read it? Examiners, Future Employees, Academics and Experts? What do they already know? What do you want them to learn, gain, and be influenced?

Writing and Structuring ReportsIt is important to take these two

considerations into your mind, before starting writing your document. In this case, you will know exactly the type of information you will include in your report.Detailed description for students, or go directly

to conclusions for experts?Try not to write so much detailed, just for the

sake of writingOn the other hand, try not to miss any important

information that should support your project.

Writing and Structuring ReportsApproaches to Writing

Top-Down ApproachEvolutionary Delivery

Note: You can adopt one of them, and you can use both!

Writing and Structuring ReportsApproaches to Writing

Top-Down Approach Use Chapter Breakdown Structure to identify the

structure of the report Identify all chapter names, sections and sub-sections

Identifying the contents of each chapter, makes writing much easier

You concentrate on a certain target in each chapter, and you don’t misdirect to another target

Helps in time management

Writing and Structuring ReportsApproaches to Writing

Evolutionary Delivery You write separate parts of your reports as the

thoughts come by. You can re-write these parts as your project

proceeds, and your information increase. So, each part evolves and matures over a period of

time as new ideas immerge.

Writing and Structuring ReportsApproaches to Writing

These two approaches (Top-Down and Evolutionary Delivery) can be combined by: Specifying the chapters, sections and sub-sections

heading and contents. By, taking the previous point as your road-map, you

can start writing these parts, taking into consideration any probability of re-writing that might be needed while the project in progress.

Writing and Structuring ReportsWhen Should I Start Writing?

You can start right away You don’t have to leave the writing to the end of

the project.In the current phase, you decide the structure of

your report, and the chapters and sections that should be included.

Then, whenever you enter a new phase (e.g. Analysis, Design, implementation, …etc) you can write down your findings in the corresponding chapters directly.

This what we intend to do in this course

Writing and Structuring ReportsThe Order to Writing

Identify Structure: Use Report Breakdown Structure to identify the content. Even if not enough information is available in this stage, use as much information as you can.

Identify Presentational Style: Use the style described in the Graduation Project Guide.

Draft the Introduction: Introduction presents the idea of the project to the reader It also makes the idea clearer to you At this stage it will be a draft introduction It should include literature review Description of the coming chapters.

Writing and Structuring ReportsThe Order to Writing

Main Body: It includes chapters like (used methods, analysis, design,…

etc.) Its content depends on the undertaken project No need to write chapters or sections in order, you can write

them as your project progresses.Write the Abstract

ALWAYS, write your abstract after the document is almost finished

Details about writing abstracts are coming later.References and Appendices

You may not use all the references you have collated.

Writing and Structuring ReportsThe Order to Writing

Arrange Contents list and the index (if required)

Proof-reading, check and correct: All group members should re-read the written documents as

a whole, and suggest any corrections or modifications. It is ok to get someone else to read it for you, as an

additional proof reading.

Writing and Structuring ReportsStructure

Title Page or Cover Sheet Abstract Acknowledgements Content Listing List of Figures and Tables Chapter 1 – Introduction Chapter 2 – Literature Review Chapter 3 –Requirements / Analysis Chapter 4 – Design Chapter 5 – Implementation and test Chapter 6 – Evaluation Chapter 7 – Conclusion

Writing and Structuring ReportsStructure – The relationship between chapters

Writing and Structuring ReportsThe Introduction Chapter

This chapter should contain the following Overview Problem Statement Goal and Objectives Scope of the Project Outcomes and Benefits Facilities and Resources Procedure and Methodology Dissertation Outline

Writing and Structuring ReportsThe Conclusion Chapter

This chapter should contain the following Project Achievement To how extent has the project met its objectives The contribution Evaluation of the following:

The development process model The Programming language Problems faced, and how it have been overcome Enhancements Lessons Learnt Recommendations and Future Work

Writing and Structuring ReportsWriting Style

Use the layout, font style, ..etc. as described in the Project guide

Grammar Style: Good reports can be ruined by poor grammar!! So pay attention to the grammar you use.

A good writing style comes with practice, the more you write the easier it becomes

Reading also helps you to improve your own writing skills.

Writing and Structuring ReportsWriting Style

Tips for a professional writing style: Try to write in the third person. Avoid using pronouns like, I, you, we, my and so

on. Example: Don’t write: I interviewed seven people to see what they thought of the system

and write: Seven people were interviewed to determine their thoughts on the systemor write: The author interviewed seven people to see what they thought of the system

Avoid complex and long sentences Avoid making several points within the same sentence. Avoid abbreviations and Jargons (ة، اللغة الغامضة�طلحات العامي�المص) Use “s/he” or “they” instead of he.

Writing and Structuring ReportsWriting Style

Tips for a professional writing style: It is common to use the past tense, since the report is describing a project that you have

already completed. Avoid jokes and personal views Avoid shortened forms: use “is not” instead of “isn’t”, use “cannot” instead of “can’t” USE SPELL CHECKER Avoid terms like “clearly” or “obviously”, since you may know the point you are talking

about so clearly, but your idea might not reach the user that “Clearly” Avoid red flags. These are claims that your personal opinion rather than facts from

literature. Example: “Requirements capture is the longest stage of the software development

processes”

Writing and Structuring ReportsWriting Style

Tips for a professional writing style: Avoid red flags. These are claims that your personal opinion rather than

facts from literature. Example: “Requirements capture is the longest stage of the software

development processes”you either add a reference to this sentence, or make it uncertain by using words like “often” or “sometimes”“Requirements capture is often the longest stage of the software development processes”