What are requirements? What is a requirements document about? Meeting with your client What to turn in How to turn the requirements in When is this due? How you will be graded Sample requirements documents What are Requirements? Generally speaking, a requirements document describes clearly and precisely what the client needs and wants, and therefore acts as the agreement between the client and the implementor. For the purposes of this project, the document is the basis for a three-way agreement, between your team, your CS 110 advisor, and your client. Why are requirements necessary? Haven't you and your client already agreed: You're going to build a web site for the new Wellesley Society for the Protection of Little Brown Birds, 'nuff said, right? Alas, that's too vague. The computer industry has had many painful experiences with projects that delivered something very different from what the client wanted, resulting in wasted time, money, effort, and often resulting in anger and lawsuits. The post-mortem analysis often showed that the mistake wasn't willful, but simply honest miscommunication about what was meant. Thus, your goal is to avoid that to the greatest extent that you can. The way to avoid this miscommunication is, obviously, to communicate: discuss with your client and your partner exactly what everyone has in mind. In the next section, we'll describe what you should be talking about. Meeting with your client Having found a client, set up an appointment with both team members present. Before the appointment, meet with your partner to check out the hall of fame sites (so you know what things are possible) and discuss ideas for the proposed pages. If possible, check out similar sites on the Web. It is easier if you know something about the content of the site. If not, your client may have to help you learn something about the topic. During the meeting, introduce yourselves and explain the purpose of your visit. Tell the client a little bit about this project. Be sure that your client understands the ground rules of your collaboration. In particular, be sure they understand that your involvement terminates at the end of the semester. After that they, not you, will be responsible for maintaining the site. Also, they should know that the site can't be hosted on the CS110 server; they'll have to find a permanent home for it. You could point the client to the CS110 site for details. During the meeting, ask your client to describe their perceived need for a web presence. Listen carefully to their ideas and desires. Be prepared to offer some suggestions, and do not be afraid to tell them when you are not sure whether something is possible or not. Your first order of business is to assess the client's real need. Will a web site really answer this need? Ask your client to specify the site's purpose and audience. Be specific! An answer like: "To inform the Wellesley College Community of upcoming events" is only a start. Decide whether the site has the right scope: you'd like to build something that is large enough to satisfy the requirements and allow you to demonstrate your skill and creativity. If they just want a short page of text, you won't be able to exercise your skills, but if they want an ambitious web site with many dozens of pages, that won't be feasible in a semester. Decide whether you can work with this person. You do not have to make up your mind on the spot. Take some time to discuss the project with your partner after the meeting. What is a requirements document about? A requirements document describes the problem to be solved, not the solution. What does that mean? It means that requirements is about what is in the web site, its contents and organization, rather than what the web site looks like. Don't jump the gun in writing the requirements document. You will be tempted to start describing the web site you will build, but that's the solution, not the problem. First, make sure you understand what the client really wants. After all, you can't very well build the web site until you know what the client wants. Spend some time interviewing your client, finding out what they have in mind regarding the goals of the site, its target audience, site organization, textual content, graphical content, navigation, links, and other aspects of the site. Bring your own ideas to the discussion as well; many clients will be hoping to hear from you on many of these topics. Looking at example sites is a good idea. Anything that can help the parties understand one another is useful. Note that your client may also confuse design with requirements, so if they say ``it should have a menu on the left,'' find out if that is an absolute requirement or a design suggestion. Try to distinguish design from requirements from the very start. The goals of a site are not always obvious. If it's a web site for the lacrosse team, should the site encourage people to try out for the team, or is it primarily information for people who are already on the team? What is the client's communicative goal? Is it to persuade people to act (say, writing letters to Congress), to excite them with enthusiasm (say, for classical Greek mythology), to inform them about facts and procedures (say, for the financial aid office), or more than one of the above? The goals of a site are usually related to the target audience. You'll want to think about aspects such as their demographics (age, sex) as well as their interests, computer savvy and so forth. For what reasons are they coming to your site? How will they get what they seek? Is there more than one kind of user? How might a site cater to both an adult researcher and a child with a novice's interest in the area? (Some CS110 students actually created a site that did this!) Find out if your client has particular organizational needs. Should two topics definitely be on the same page? Should there be a directly hyperlink between two things? Many times these won't matter and should be left to design, but sometimes there are particular requirements. Talk about the client's desires and goals with respect to graphical design. How important is the appearance of the web site, compared to the content? Is a particular color scheme required, or does the client have a preferred layout? In general the graphical design of the site will be up to you, but you should discuss the client's specific requirements, if there are any. Once you start talking about graphical design, it is easy to get ahead of yourself. Remember, at this stage you should be collecting the client's requirements, not making design decisions. Find out if your client has any special, idiosyncratic requirements. Here are some examples: The user should be able to get to any reference page in three clicks or less. Certain pages should only be viewable by the Wellesley community. The background and fonts should suggest nostalgia and antiques. Every page must load within 2 seconds over a 56K modem. Finally, you should be clear on what requirements are necessary versus desirable (true, we probably shouldn't call them "requirements," but that's just what we call the document that you're writing). The discussions about requirements are probably the time in the project when your client must spend the most amount of time with you. Hopefully, you have chosen your client wisely, and they will be willing to do so. It is not a bad idea to look ahead at what you'll have to do for the design document (the next assignment). The more you can anticipate that assignment, the easier it will be. For example, by the next assignment, you need to have collected all the textual content of the site. Since much of that content will come from the client, you should begin talking to your client about obtaining it. You don't want the web site to be held up waiting to get some text or even graphics from your client. As you begin drafting your requirements document, it is a good idea to give drafts to your client and discuss them. Once an idea is clearly presented in written form, people often realize that's not what they meant. Discussions with your client are also a good way to ensure that the requirements are clear and complete. This is not an assignment that should be begun the day it's due. What to turn in Turn in a document, written as a web page, containing a structured essay covering the following topics. Administrative details: the name of your client, and his or her position in the organization The server on which the site will reside after the end of this semester. Sometimes, your client will not yet know, so just state that. The name(s) of those who will maintain the site after the end of this semester. Almost any site requires regular updates, so it's important to line up who will do this. Again, you may not yet know, but it's good to begin the search. The site's purpose and goals and how they will be accomplished by the site. Try to draw a connection between the goals and specific content elements of the site. Who is the intended audience or typical user? Describe them and their needs for information and other content. A description of the content of the site and how it is organized. Think of this as like the structure of a paper: it doesn't have to spell out the sentences or even the paragraphs, but it should mention major sections and even a few salient subsections. In your conference, be prepared to discuss the site's content, and to explore the feasibility of its design. The document must be in essay form (paragraphs of text, not just a bullet list or set of bullet lists), although you may use bullet lists when they are appropriate. It must be written in HTML; you can use NotePad or TextWrangler or Dreamweaver or any web-page authoring software you like, but the finished product is a web page, not a MS Word document or any other non-web document. It should be about a page long. How to turn it in You will hand in your assignment as soft-copy only. The soft copy must be uploaded to your team account on the CS department server, and it must be put in the public_html folder and named P1_requirements.html. (We will look for a file with just that name, so now is not the time to be creative.) The timeliness of your assignment is determined by the timestamp on your electronic submission. Standard Reminders: You should ensure that any submission is clearly marked with your team name and the names of both team members. Also, once the deadline has passed, do not edit the file or re-upload it; we will be looking at the file creation times to ensure that you submitted the assignment on time. When the requirements are due You already know that all the deadlines are posted on the web here. No assignments will be accepted late. How you will be graded Because each team will be doing a different project, your advisor will necessarily have to exercise some judgment when grading. Nevertheless, we will follow these guidelines : Because we have given you a complete list of the elements of the requirements document (see What to turn in), there will be substantial deductions for any element that is entirely missing. Please don't hide things from us; make it clear that you have covered all the required elements. Points for the discussion of the site's goals. A discussion that is clear and detailed will get full credit. Discussions that are vague or generic will receive less. Points for the discussion of the intended audience. An excellent discussion will describe how its audience differs from a generic one and how those differences pose a challenge for the web design. Points for description of the site's contents. Grading is primarily on coverage--an excellent description will be comprehensive and detailed. Points for being prepared for the meeting with your project advisor. Both team partners must attend the meeting. Prior to the meeting you must have met with your client and uploaded a draft of the requirements document into your team directory on the CS110 server. It will be used for the discussion. Points will be deducted for spelling, grammar, punctuation and other mechanics of writing. You can reference the requirements document feedback form that we will be using for grading if interested. Sample requirements documents Here are some examples of requirements documents. Notice that they're all different, so don't treat any of them as a template. However, reading them may give you some idea of how people have done this in the past. Note that these students did well, but not perfectly, so you should strive to do even better! Magner Corporation of America Morton Birkin Medieval and Renaissance Studies International Relations Council Taiwanese Cultural Organization Introduction | Syllabus | Assignments | Documentation | Project Computer Science 110 Date Created: June 28, 1998 Last Modified: January 2007