Deliverables
•
- project description. This is a high level description that introduces the casual observer to the project. For some projects, this will become a brochure that you would use to "sell" your product
- contact information, including one button email to the development team
- contract
- project plan. Once agreed to, all changes to the project plan need to be recorded on the website. This can be done with a simple log of changes.
- schedule for all key meetings
- Functional spec
- use cases
- requirements
- design document
- all user manuals
- test plan
- journal of meetings and decisions. This is the place to capture decisions that have been made and discussions that have been had. Capturing the information will help assure consistent understandings and (hopefully) reduce the number of times the same point will be rediscussed.
- related links. Related links are those that point to similar projects that you can learn from, domain-specific content that will frequently be referenced, and pointers to the technology that is being used.
Contract (initial Feb 2, signed by Feb 7) Word template The contract is the agreement among the team, the client, and the professor as to what will be delivered when. Missed commitments from the contract cost you reputation and potentially grade. We ask the client to actually sign the document to be sure that he or she really reads it. Contents of the contract include
- General description. Covers the context (e.g., dealing with aparticular population or teaching a particular subject) and the purpose of the project (e.g., is this a game for pure entertainment or does it have an educational purpose).
- Participants. Who is on the team, who is the client, and who are consultants that you will be using.
- Requirements. Correctness of a project is defined as meeting requirements. Remember to include inverse requirements (i.e., things that are not to be done). Primary requirements are mandatory; secondary requirements are recommended as they will help you with your design; tertiary requirements are at your discretion.
- Constraints. Constraints are a specific form of requirement that puts limits on your potential solutions. Examples of common constraints are the platform that the system must run on (especially if its an old one!), resources that can be used (e.g., memory), or performance constraints.
- Deliverables. The artifacts that the client is expecting: code, what types of manuals, what kind of software package (e.g., downloadable or installer wizard). Does not usually include dates.
- Resources required. This should include hardware, software, and people's time.
- Obligations. Identify the explicit obligations of the team and the client. This can include time, getting resources, meetings, or specifics about deliverables.
- Risks. If you have some dependencies or concerns that may cause the project to not succeed, identify them here. Potential risks are fundamental designs that may not be practical (e.g., the player can't distinguish the sounds as expected), delivery of or access to equipment (either hardware or software), or any specific activities that you don't know how to estimate.
- Milestones. Basically the deliverables and additional checkpoints with dates associated with them.
Project plan (Jan 31) Sample. The project plan captures your work plan. Most teams use Gantt charts or simple tables. You should limit your time spans to no more than 2 weeks. That is really the most slip that you can recover from in one semester. If you don't feel that you can recover from a 2-week loss, you should have a smaller timeframe. I recommend a 1-week timeframe. At the end of each identified activity, you should have a "deliverable" that allows you to say unquestionably whether or not you have met that goal. All class deliverables should be identified on the project plan. Associated with the project plan needs to be an indication of who is doing the activity. Once the project plan has been agreed to between the team and the professor, all changes to it need to be tracked.
Functional Specification (Jan 30) Sample. The functional specification (or spec) is a document from which a developer can develop the system. It should be complete enough that it could be used as a bid request out to a third party. Key components of the spec are use cases and requirements.
Use cases: There are two forms of use cases that are often used: a graphical form that shows how the different use cases relate to each other and a textual form that talks about the details of each use case. The detailed use case needs to include error cases. Identifying the error and unusual cases is one of the most valuable parts of use cases, as designers and developers often miss a number of these points. For your projects, the textual form is required. If the graphical form helps you put the pieces together, that is fine. Associated with each case needs to be a description of the user. This needs to be in enough detail to allow you to reason about the task. For example, the one time user and the repeat user should be treated separately in order to confirm that your application desoign addresses the needs of both types of users. Use cases should address all types of end users as well as administrators. Pay special attention to first time uses as they often have a different set of tasks that are being performed.
Requirements: The requirements document will be primarily gathered from the contract and the use cases. Remembering that the requirements define the correctness of a program, you can expect me to go through the requirements at the end of the course and see if you have met them. One of the key values of the requirements document is the collecting and collapsing of information from the use cases into common requirements that are translated into programming terms rather than domain and user terms. For example, if there are two different file structures that are needed, one of the requirements might be the consistency of the two structures. Or as you work through the different use cases of a game, you will find related behaviors; identifying how those behaviors need to be consistent might be another requirement. If your application is not permitted to do something -- such as overwrite a file or share certain components -- you should identfy these as constraints or inverse requirements.
Design document (team scheduled) The purpose of the design document is to be the guide for someone who needs to understand the code to maintain it, extend it, or re-use parts of it. While "all of the information" is in the code, the concepts that underlie it are lost in the details. Consider this document a tutorial for your code. While it is true that the reader of the document will be familiar with basic programming and object-oriented concepts, that is all that you can assume. Do not assume a knowledge of the domain of the application. (How good was your understanding when you started the project?) When I ask your classmates to critique this document, I will give them a specific task that they want to accomplish and the question that they will be answering is whether this documentation will allow them to do this in a reasonable time. In the first two sections, you are more apt to find that graphical representtion helps in the understanding, but in the later sections, you will probably find that text will work fine. Specific elements to be included in the design document are: In addition, consider this the repository of any other information that will be helpful to the next developer. Consider this the one document that survives for the developer and if you have easily included versions of your use cases, requirements, and any flow diagrams that helped you develop the work, include them. If they can not easily be included, you will not be penalized.
- Architecture. The architecture describes the highest level external view of the software system. It is fine to use one of the software architecture models presented in class or to define your own. An architecture description will typically have between 3 and 7 components. This should be the highest level of decomposition that you use to reason about the system. When you are discussing the implications of a design change or how to divide up work, you should be able to easily map that back to the architecture. The architecture can be documented as a picture with a paragraph explaining the model. While the architecture may be modeled after one of the standard ones, your architecture should translate into the application terms (e.g., a repository should be labeled by the data that it captures). If you are using a standard model, be sure to state so explicitly.
- Decomposition. The next three sections give different views of the model defined in the architecture. The terminiology used here is not object-oriented because not all class projects are OO. If your project is OO, feel free to use the OO terminology. This is the next level of decomposition from the architecture. It should flow from the architecture and relate the components, but not define any of the components completely. That's what the next two sections do!
- Modules. Describe the primary modules that you are using and the relationships among them. Whenever you are defining relationships among components, you may find a picture a useful addition to the write-up. The details of the modules are described later. The purpose of this section is to relate them to each other.
- Processes (if relevant). If your application uses concurrent processes or multiple threads, explain why they exist and what they are doing. For example, a system with multiple inputs may have different processes monitoring those inputs. Also cover when they are created and destroyed.
- Data (if relevant). Describe all the key data components of the system. Specifically, this is the persistent data -- files that you use or create and databases. The detailed specifications come later; the purpose of this section is again to give a high-level view of what the files are, how they are used, and how they relate to each other. If there are multiple tables in a single database, this should be explicitly covered. If there is no external data associated with your application, this section is not needed.
- Detailed module definitions. For each module, you now will describe its specifics, including the interfaces, details of decomposition, and key algorithms. If this is a class, you will define its attributes and their types as well as all of the associated methods. You need to describe what functions the methods are doing and a natural language explanation of the attributes. In addition, if there identifiable invariants, pre- or post-conditions of the methods, they should be documented here. In addition this is the place to define any of the key algorithms that you use. If you are using a standard routine or data structure (e.g., a binary tree), you do not need to do more than state that fact.
- Detailed data definitions (if relevant). For any file or database, a complete definition of the format needs to be included. The definition should include both the format and use of each field within the application. If there are constraints on fields, they should be included. The relationship of individual fields are also defined here. If there is no external data associated with your application, this section is not needed.
- Design decisions. This is the place to document any decisions that you made that effected the overall design of the system. Any dependencies that the application has should be explicitly stated here and the reason for that dependency explained. Decisions about things that you chose not to do are as important as those that you chose to do.
User manual (team scheduled) The user manual is a document that is intended for the users of the system. If there are different types of users, there minimally must be different sections for them. The manual needs to be written at an appropriate level for the intended audience. If the user is a reluctant computer user, the manual should be very specific and avoid jargon. This is not necessary for someone who is more comfortable with computers. The skill level of the user should be defined in your user descriptions. For applications intended for very young users, think of the user manual as the document that the teacher will need to interpret. The closer that you can get to the teacher being able to simply read the manual to them, the more on target the writing is. Remember that users are not very tolerant of long-winded documents. Get the essential information written up front. If there is more detail needed for special cases, put it in a separate section. Of course the goal is that no one ever has to read a user manual, but you should not assume that it is that intuitively obvious! For most school-related projects, there will be two users: the student and the teacher. Do not assume that the teacher is the administrator. While in some cases this may be true, you need to separate the roles.
Administrator manual (team scheduled) The administrator manual is intended for the person setting up the system. This needs to include all software and hardware dependencies, download instructions, and any hardware set-up instructions.This is the place to document what systems have been tested, what the expected compatabilities are and any known incompatabilities. If the administrator needs to set up ids and passwords before the system is fully deployed, this needs to be covered inthis manual. The administrator manual should include a complete set of easy-to-follow instructions of how to deploy the system in a new environment or how to redeploy the system if it needs to be restarted or refreshed. You again need to be cognizant of the skill level of the administrator. You can assume that it is an adult, but given the intended audience, you must determine the appropriate level of skills that you can assume. This should be defined in your user descriptions.
Test plan (team scheduled) The test plan is my guide to testing. While a general test plan would cover unit, system and user testing and answer questions about tools and types of users, the focus for this document is the test cases that are needed. Consider different test environments, error conditions and data-specific test cases.
Code (team scheduled) Aside from functioning properly, the code is expected to be consistently written and well documented in a uniform manner. Assure that your team is following consistent standards. The only way that I should be able to tell who wrote a module is by the fact that the person's name is included in the comments.