Projects Proposal for Software Design Documentation | CSSE 497, Study Guides, Projects, Research of Computer Science

Download Projects Proposal for Software Design Documentation | CSSE 497 and more Study Guides, Projects, Research Computer Science in PDF only on Docsity! Software Design Documentation for <project name>, revision # Team <#> <Authors> <Date> 0. Guidelines to using this template a. Lifetime: This is an evolution of your architecture document. At some point, the architecture may simply extend into becoming the design document and you rename it, or you may instead keep two documents. For senior project, we recommend just extending the architecture document to become this, but it’s your choice! On complex projects there are typically multiple design documents.1 In any case, the high level and more detailed design info all need to be kept up to date. The rest of this discussion refers primarily to what would be in the more detailed-level design document. Once written, the document should go under change control, like your other documents. b. Transition from requirements: In the same way the architecture is intended to “answer” the problem statement you wrote, the detailed design answers the detailed requirements. When you get done, a reader ought to be able to look back and forth between the requirements and your design, and figure out where you talk about solving any particular area of the requirements. So, for example, lots of cross-references are useful. If you want to get fancy, you could try hyper- linking back and forth. The architecture document should already sound like it elaborates at least a bit on the most critical parts of the requirements captured in use cases and in the supplementary spec. The design spec fills in the missing parts. For example, the design spec will have a more elaborate version of your use cases, one showing design information as well as what you got from your client and users. c. Readability in general: Whether or not this design should be readable by your client depends on whether they are a technical person. It certainly should be understandable by everyone on your team! Standard readability rules need to be followed – like avoid ambiguity and repetition, and explain what an acronym or jargon means the first time you use it, etc. d. Design information: Ideally, this should explain to developers how the design is supposed to work, in such a way that they could develop code from what they see here. 1 If you write separate, additional specs, these often are on separate subjects. For example, an Interaction Design spec with all the user interface information, a database design spec, use cases detailed with design information, an OO design document, and an enlargement of the “supplementary spec” with all the other functional and non-functional design data. e. Transition to testing: Finally, it should guide testers as to what additional kinds of “white box” testing might be needed to do integration testing and system testing, beyond what they see in the requirements for “black box” testing of requirements. f. Overall length: Target 25 pages as a guide, for the finished version of this document. The real intent is that it’s usable by your team, as the more detailed, reliable reference for “what it’s supposed to look like” as a design. However, the goal is that this document bridges between requirements and the coding and testing which follow, guiding and supporting your implementation. When you believe that your team can code and test from this document, maybe you’re done! Your instructor will want to verify this decision. g. Appearance: Like the architecture document, the design document should be “half pictures.” Each diagram or other figure should be fully annotated and explained. See section 6, below, for more info on that. h. Architectural style: It should remain clear from this document what the overall “style” of your system is, and you should show this in the images as well as talking about it. See Garlan & Shaw’s famous article2 for an introduction / refresher on this subject. (Of course, you may use more than one such style for different things the system does.) i. Interfaces: This document should provide all necessary guidance to the key interfaces of the system, both to the outside world and also within the system itself. For example, if the system uses Corba to talk from its clients to servers, or PHP, or SOAP, there should be at least pointers from here to the other documents which detail those interfaces. Note that interfaces are a major part of the Element Catalog in Section 6, below. Section 7 describes the Development and Run-Time design of your system. Theoretically, that should include a lot on the framework’s OO interfaces, and important ones of these should be discussed. Of course, there’s going to be real code to support this, as well. ---------------------------------------------------------------------------- <Table of contents. You can use what’s built into Word.> 1. Introduction <Describe the purpose of the document and give a brief overview. Include a guide for different types of stakeholders. For the design document, this should include people coding and testing the system. > 2. Background <As in the architecture document, give a brief statement of the problem and the intended solution. Describe the main stakeholders and their concerns. Describe any existing systems, especially those that have interfaces with your system. Include a shortened 2 If the regular link doesn’t work, see copy here. Allocation – This one always shows hardware as well as software, a larger picture of the system in its environment. Especially, it shows what software on what box talks to what other software on its box. The links between the boxes should be as informative as possibly in their legend, saying things like what protocols or interfaces are used, and what the capacity of these links will be. However, there are additional kinds of allocation views that you may also need, like one showing how it will be deployed or installed. Data – These include things like entity-relationship diagrams for the database. For this design document, there could be quite a bit here! If you use flat files, their file layout should be shown. If your system interfaces with other systems, those interfaces should have tables sequence diagrams showing the interfaces. The goal is to have “enough” design information that any of your team members can create parts of the system in a consistent way based on that guidance. User interface – Now is the time to show detailed versions of your interaction design images. Your use cases go here, and each one is an expanded version of the use cases you had for requirements. The requirements use cases may have said things like, “next accept the user’s password.” This document should explain how that step is to be done. Typically, the use cases are up to twice as long with all this design information. As before, the software framework supporting user interaction would be described in Section 7. Other – Any other figure which supports what you are designing, and which would help guide implementation. For example, if you have a complex communications algorithm, you might have a state diagram showing the states it moves through under various conditions. > 7. Framework and Overall Design <Note that this is now about the whole system, not just the architectural framework. You might write sections of this as you develop the associated code, or instead do all the writing before coding beyond your architectural framework. You should refer to the views in the previous section. Describe how the design is to be utilized and maintained as people code. Describe also how testing can be done to verify that the design and coding are correct. This information should fit in with your test plan. This discussion should elaborate on the framework description you had in your architecture document. It should draw on facilities you put into your framework, things like “model view controller” and “Gang of Four” patterns which make it easy to add the specific features. > 8. Acknowledgements <Acknowledge the help of the customers and developers. Also give thanks for any other sources of material you used, such as authors of patterns.> 9. References <Include citations here, both internal to the team and external. Use a standard format, such as IEEE (http://standards.ieee.org/guides/style/section7.html) or ACM (http://moon.cse.yzu.edu.tw/acm/docs/ihhuang/citation/). Use a standard format, such as IEEE (http://standards.ieee.org/guides/style/section7.html ). > 10. Revision history <Table containing the revision number, date, who made the change, what the change was> 11. Appendices <If you have other material you want to include, place it here. For example, you might include a glossary of technical terms and abbreviations.>