G U I D E F O R W R I T I N G A S Y S T E M D E S I G N D O C U M E N T

Transcription

1 King Saud University College of Computer and Information Sciences Information Technology Department G U I D E F O R W R I T I N G A S Y S T E M D E S I G N D O C U M E N T D OCUMEN T P R EPARED F OR IT : SW ENGINE ERING P R OJEC T S Version: 2 Date: December 2009 Prepared by: Maha Al-Yahya, Latifa Al-Abdulkareem and Sarah Al-Khudair.

2 INTRODUCTION "The System Design Document, SDD, shows how the software system will be structured to satisfy the requirements identified in the software requirements specification. It is a translation of requirements into a description of the software structure, software components, interfaces, and data necessary for the implementation phase. In essence, the SDD becomes a detailed blueprint for the implementation activity. In a complete SDD, each requirement must be traceable to one or more design entities." [1] STYLE CONVENTIONS FORMAT The SDD document should be typed. All text, Figures and Tables should appear on only one side of each sheet of paper. All pages other than the cover sheet should have page numbers that begin with 1 on the first page after the title page, and should continue through the last page of the reference page, but not the appendices. The right-hand margin should be 1.5 cm and the upper and lower margins cm. The left-hand margin must be 4 cm on each page of the document because of the binding. The margin instructions should be followed in the appendices as well. The font size in the text should be in 12, in subsections 12 and in the main headings 14. The main headings are to be written in capitals and placed at the beginning of a new page. All headings are to be in bold letters. Leave two empty lines under the main heading, two empty lines above the subsection and one empty line under it. The headings should not have more than three numbers. A line spacing of 1.5 should be used in the text, 1 on the title page and in the abstract. The font to be used is Times New Roman. The page number is placed in the lower right corner. The text should not be indented and both margins on the page should be justified. When a paragraph continues on the next page, at least two lines of the paragraph should be left on the upper or lower end of the page. The paragraphs are separated from each other and from the headings with one empty line. A new chapter is started on a new page. One empty line is needed to separate two paragraphs. TEXT The text of the report should be written in complete sentences. The style should be formal. Formal style means to avoid slang, clichés, abbreviations that are common in spoken English or advertising. It is convention that formal reports are written in the third person. FIGURES AND TABLES All Figures and Tables should have a number and a caption. If a figure or table is extracted from a source, the source should be cited in the references. Page 2

3 SDD REPORT CONTENTS A template for the project SDD report is attached. A project SDD should include the following components: The title page should include: TITLE PAGE University, College, and Department centered University logo on right hand side Project logo just above the title Project title: The title should be a stand-alone statement that can fully describe the project by summarizing the main idea of the project. The title is supremely important. A successful title will attract readers while an unsuccessful one will discourage readers. Compose trial versions of the title as early as you can. Student names in alphabetical order, along with the IDs. Supervisor name Year and semester in HIjrii and Gregorian TABLE OF CONTENTS A table of contents should list each of the main sections of the SRS report, and the beginning page numbers for each section. INTRODUCTION[2] The introduction should provide an overview of the entire SDD as follow: Describe the purpose of this document (why do we need this document?) Describe this document's intended audience. Provide a complete list of all the applicable, referenced and any other pertinent documents such as: o Documents which provide background and/or context for this document o Documents that result from this document (e.g. a test plan or a development plan) "If you used any other types of documents to arrive at this design, list them here."[3] Summarize (or give an abstract for) the contents of this document. "Describe what the rest of the SDD contains and explain how the SDD is organized. Constraints - Briefly describe any restrictions, limitations or constraints that impact the design or implementation."[3] Page 3

4 SYSTEM OVERVIEW This section deals with a summary (one paragraph) of the overall system design aspects, by giving a brief functional description with key concepts: Provide a top-level description of the system and its major external interfaces to aid the reader in understanding what the software is to accomplish. Reference appropriate graphics, illustrations, tables, etc., to show functions. [4] SYSTEM ARCHITECTURE "Architectural Design: A diagram showing the major subsystems and data repositories and their inter-connections. Supplement with text as needed. Provide descriptions of the design components. Architectural Alternatives: Discuss other architectures that were considered. Design Rationale: Discuss the rationale for selecting the architecture, including the critical issues and trade/offs that were considered." [2] DETAILED SYSTEM DESIGN "Most components described in the System Architecture section will require a more detailed discussion. Other lower-level components and subcomponents may need to be described as well. Each subsection of this section will refer to or contain a detailed description of a system software component.(i.e. the following will be written for each component in your system). Provide a detailed description of this software component (or a reference to such a description)..the discussion provided should cover the following software component attributes: Classification The component kind, such as a subsystem, module, class, package, function, file, etc. Definition The specific purpose and semantic meaning of the component. Responsibilities' Reference The ID of the related requirement from the SRS document. Constraints Any relevant assumptions, limitations, or constraints for this component. This should include constraints on timing, storage, or component state, and might include rules for interacting with this component (preconditions, postconditions,.) Composition A description of the use and meaning of the subcomponents that are a part of this component. Pseudocode A complete and concise pseudocode for this component. Follow these links for more details and examples: Page 4

5 DATA DESIGN Provide this section if there is a Database attached to your system. DATABASE DESIGN "List and describe database(s), tables, fields, and schema."[4] In this section provide the following: USER INTERFACE DESIGN USER INTERFACE DESIGN OVERVIEW "Provide a high-level description of the user interface for this system. Describe any systems requirements (e.g., performance or usability) associated with all of the user interfaces."[5] USER INTERFACE NAVIGATION HIERARCHY "Provide and describe a diagram of the navigation hierarchy that illustrates how a user moves through the user interface."[5] USER FUNCTION (OR USE CASES) INTERFACES "Accurately and comprehensively document each user function or use case that requires an interface individually in a corresponding subsection. Label each subsection appropriately and title each subsection descriptively to indicate the function or use case being documented. FUNCTION X (OR USE CASE X) 1. Provide a description and an image of each screen, report, or other user interface within this function or use case. 2. Provide a Screen/Other User Interface Fields Table that includes descriptive information for each field that appears on the screen or other user interface. In addition, if the data is selected from a pick list, include the list of possible values or their description. If the content of a field is derived from client side calculations using other fields or values, then specify the algorithm for the calculation in a descriptive footnote to the table. If the content of a field is derived from server side calculations or lookups, then specify the source of that calculation (e.g., the class or stored procedure where the calculation occurs). 3. Also, specify the error messages to be displayed when the input does not meet requirements for the field, and provide image screens for them."[5] Page 5

6 REFERENCES Always give complete citations for material on other sources. A proper reference involves two components: the citation in the text and the complete bibliographic entry in the References section. Use the Institute of Electrical and Electronics Engineers (IEEE) style for referencing. For more information see APPENDICES An appendix is included at the end of the report. It contains information referred to in the report that's too large to fit in the body of the report. Provide any appendices you have in this section. Appendices include the material needed for the report but which is unnecessary to include in the text itself (sample agreement form with client, graphs, and interview forms). The appendices must be referred to in the text and they must have all the necessary information needed for interpretation. Appendices are situated at the end of the thesis and numbered consecutively. The written form for reference to appendices within the text is: Appendix 1, Appendix 2, etc. In the References it is: APPENDIX 1, APPENDIX 2, etc. REFERENCES FOR THIS GUIDE [1] IEEE (1998) IEEE Recommended Practice for Software Design Descriptions. IEEE Std , The Institute of Electrical and Electronics Engineers, Inc [2] Bradford D. Appleton," A Software Design Specification Template", [3] CMSC 421 Staff, "System Design Document Template", Spring [4]"System Design Document Template", New Mexico Department of Information Technology, August 14, [5] " System Design Description", Texas Project Delivery Framework, Version 1.2, 14 JAN Page 6