Presentation on theme: "Lecture 3: Writing the Project Documentation Part I"— Presentation transcript:
1 Lecture 3: Writing the Project Documentation Part I Graduation ProjectsLecture 3: Writing the Project DocumentationPart I
2 Topics that will be covered Structuring ReportsWriting AbstractsReferencing MaterialPresenting DataDocumenting SoftwareCommenting ProgramsWriting User Guides
3 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 resultsGood work (software for example) could be ruined by a poor report, that doesn’t justify your practical work right.
4 Writing and Structuring Reports ConsiderationsWhat is the purpose of the report?Best MarkWork DisseminationProvide Literature ReviewInspiring othersFulfill Requirements of your courseWho 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?
5 Writing and Structuring Reports It 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.
6 Writing and Structuring Reports Approaches to WritingTop-Down ApproachEvolutionary DeliveryNote: You can adopt one of them, and you can use both!
7 Writing and Structuring Reports Approaches to WritingTop-Down ApproachUse Chapter Breakdown Structure to identify the structure of the reportIdentify all chapter names, sections and sub-sectionsIdentifying the contents of each chapter, makes writing much easierYou concentrate on a certain target in each chapter, and you don’t misdirect to another targetHelps in time management
8 Writing and Structuring Reports Approaches to WritingEvolutionary DeliveryYou 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.
9 Writing and Structuring Reports Approaches to WritingThese 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.
10 Writing and Structuring Reports When 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
11 Writing and Structuring Reports The Order to WritingIdentify 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 readerIt also makes the idea clearer to youAt this stage it will be a draft introductionIt should include literature reviewDescription of the coming chapters.
12 Writing and Structuring Reports The Order to WritingMain Body:It includes chapters like (used methods, analysis, design,…etc.)Its content depends on the undertaken projectNo need to write chapters or sections in order, you can write them as your project progresses.Write the AbstractALWAYS, write your abstract after the document is almost finishedDetails about writing abstracts are coming later.References and AppendicesYou may not use all the references you have collated.
13 Writing and Structuring Reports The Order to WritingArrange 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.
14 Writing and Structuring Reports StructureTitle Page or Cover SheetAbstractAcknowledgementsContent ListingList of Figures and TablesChapter 1 – IntroductionChapter 2 – Literature ReviewChapter 3 –Requirements / AnalysisChapter 4 – DesignChapter 5 – Implementation and testChapter 6 – EvaluationChapter 7 – Conclusion
15 Writing and Structuring Reports Structure – The relationship between chapters
16 Writing and Structuring Reports The Introduction ChapterThis chapter should contain the followingOverviewProblem StatementGoal and ObjectivesScope of the ProjectOutcomes and BenefitsFacilities and ResourcesProcedure and MethodologyDissertation Outline
17 Writing and Structuring Reports The Conclusion ChapterThis chapter should contain the followingProject AchievementTo how extent has the project met its objectivesThe contributionEvaluation of the following:The development process modelThe Programming languageProblems faced, and how it have been overcomeEnhancementsLessons LearntRecommendations and Future Work
18 Writing and Structuring Reports Writing StyleUse the layout, font style, ..etc. as described in the Project guideGrammar 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 becomesReading also helps you to improve your own writing skills.
19 Writing and Structuring Reports Writing StyleTips 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 systemand 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 systemAvoid complex and long sentencesAvoid making several points within the same sentence.Avoid abbreviations and Jargons (المصطلحات العامية، اللغة الغامضة)Use “s/he” or “they” instead of he.
20 Writing and Structuring Reports Writing StyleTips 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 viewsAvoid shortened forms: use “is not” instead of “isn’t”, use “cannot” instead of “can’t”USE SPELL CHECKERAvoid 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”
21 Writing and Structuring Reports Writing StyleTips 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”