Writing Assignment:
Report on S2S Project Quality

<Course, Semester, Year>

Date assigned: XX

Date due: YY (2-3 weeks later)

• Electronic version due by 8am via Blackboard
• Hard copies due by noon, either in class or to Dr. Almstrum
• Dr. Almstrum will assign the specific projects to each student! The assigned projects are listed at <URL>.
• Submission details are given below

---

Table of contents:

• Content of the report
• Guidelines for this assignment
• Layout and Writing style
• Length of answers
• Submitting the assignment
• Grading

Additional materials relevant to this assignment (and also listed in the narrative below):

• <URL to assigned projects for individual students> [to facilitate acknowledged collaboration]
• Optional template for the report
• CS373 writing resources page
• Sample writing assignment feedback
• Links to all S2S projects
• CS373 web analysis resource page
• CS373 web resources page
• Documentation standards from previous semesters
• S2S directory structure requirements
• Blackboard tutorial on using the dropbox

Content of the Report

In this assignment, you are in the role of a consultant hired by S2S Industries to provide recommendations about two different projects completed by past CS373 teams. Your job is to advise S2S Industries about what remains to be done in order to ensure that these projects are ready for release. Your report will help determine future work to be done on these S2S projects, so you must strive to make the results constructive and accurate.

Your report should include exactly the sections given below. Replace all occurrences of codename1 and codename2 with your assigned project codes.

1.0 Products reviewed

List the codenames, team name, semester, and team number for the products that you reviewed. Using a list or table format is a good approach to presenting the relevant information on each project.

If you consulted with any classmates, acknowledge these collaborations here. Give the name(s) of your collaborator(s) and the nature of the collaboration in each case. See below for further discussion of the rules for collaboration. Do not leave this blank -- you must address this issue, whether you collaborate with someone or not.

2.0 Review of project codename1

2.1 About this project

• 2.1.1 Project summary: Briefly describe the project in your own words. Do not simply copy what the team has written. Make the description appropriate for introducing potential clients to the project.
• 2.1.2 Recommended environment: Describe the recommended environment(s) for this project. Be as complete as possible. You should be able to glean this information from the SRS, the TO-USE.html file, the team reports, and other documents.
• 2.1.3 Team's recommendations: Briefly summarize the team's recommendations for future work (from their final report, not from your own observations).

2.2 Approach for this investigation

• 2.2.1 Steps in the investigation: Give a brief discussion of your approach to investigating this project. Consider the project from two sides: The developer side and the client side. Your approach should include at least the following aspects:
  • Thoroughly investigate all aspects of the project via the URLs for the project. Links to all S2S projects appear on the page http://www.cs.utexas.edu/users/s2s/admin/s2s-cross-ref.html.
  • Investigate the Unix directory structure for the project. You can do this during a Unix session (use the Unix command cd ~www/users/s2s/latest/codename1/ to get to the proper directory). You can also use a tool such as Fetch or WS_ftp to investigate the directory structure without needing to log on under Unix.
  • Download the project (if necessary) and run it.
  • Use at least one web site analysis tool to provide you with additional information beyond what you will see by inspecting the site. (See the CS373 web anaysis resource page at http://www.cs.utexas.edu/users/almstrum/cs373/general/web-analysis.html.)

This section should only describe your approach. Your findings do not belong in this section.

• 2.2.2 Investigative environment: Describe the exact environments in which you tested the project. Run the project on at least two different platforms (PC, Mac, Linux ...), at least one of which is a platform for which the project was designed. List the platforms, operating systems, display resolution, web browser brands and version numbers, and information about the connection to the Internet. For example: "I tested the wizard3 project on a PC running Windows 95 with a 1024x768 display resolution. I used Internet Explorer 4.01 for all browser-based portions. The connection to the Internet was via a 56K modem (Telesys dial-up)." Another idea is to use a simple table to organize this information.

2.3 Findings

• 2.3.1 Documentation:
  • Summarize how well the project's documentation follows that semester's documentation standards. The documentation standards from previous semesters through Fall 2004 are listed at http://www.cs.utexas.edu/users/s2s/admin/s2s-documents.html. For later semesters, you will currently need to access the documentation standards via the class pages for each semester
  • Discuss the quality of the content of the final versions of the documents. Give commendations as well as critiques: What did the team do especially well? What did they do poorly?
• 2.3.2 Directory structure: How well does the directory structure correspond to the requirements for the S2S directory structure? Because the requirements have evolved over the semesters, there may be differences from the requirements for this semester. The page for this semester is not yet posted, but will soon be available. It will be similar to the one from the Spring 2004 semester, http://www.cs.utexas.edu/users/almstrum/cs373/sp04/doc-stds/s2s-dir-struct.html.
• 2.3.3 Quality under operation: What is the quality of the product when you run it? Does it run as expected? Does it download and run reasonably quickly? Is there adequate help information for the intended audience? If the product fails while running or cannot even be started, include (perhaps as an appendix) a complete description of what you tried and the responses you received; this information can be invaluable in diagnosing the problem with the software.
• 2.3.4 Quality of code and component files: Inspect the files that comprise the project (which should be located in the product's src/ directory). Discuss how well the code meets quality criteria such as maintainability, readability, testability, and reusability.
• 2.3.5 Legal issues: What are the potential legal problems? For example, does the project make use of copyrighted materials without permission? Does the project use trademarked phrases inappropriately? If no problems show up, be sure to report your finding with a non-trivial statement, for example "The project has no apparent legal problems". Include a brief discussion of how you arrived at that conclusion.
• 2.3.6 Testing approach and results: Look over the test descriptions given in the Verification and Validation Plan (VVP). Compare the team's planning to what they reported in the Verification and Validation Results (VVR). How well do you feel the team did with planning and executing their verification and validation activities? Do their results help raise your confidence in the quality of the product? Motivate your conclusions.

2.4 Recommendations

• 2.4.1 Recommendations for fixes: Summarize and prioritize the problems you discovered according to how serious they are. For each category of problems, propose a strategy for fixing them. [Do not give an exhaustive list of the problems here; the detailed description of problems belongs in section 2.5.]
• 2.4.2 Recommendations for enhancing the product: Consider how this project could be extended by future teams. Your recommendations may be inspired by what the team suggested in their final report or may go in an entirely different direction. (Write the recommendations as suggestions to a future team, not as advice to the team that did the original work.)
• 2.4.3 Strategy for continued work: End this part of your report with a summary of the work that you feel should be included in the next phase of work on this project.

2.5 Summary of faults and problems

This section will include detailed information about the faults and problems you find in this project. Organize this information in a way that makes it easy to read, for example as a table. The faults table can be considered as separate from the page limit suggested below, since some investigators may discover a large number of problems. If you encounter broken links or problems with specific images or pages, give the URL and precise instructions that will allow the maintenance engineer to quickly recreate the problem and begin to solve it.

3.0 Review of project codename2

3.1 About this project (as above)
3.2 Approach for this investigation (as above)
3.3 Findings (as above)
3.4 Recommendations (as above)
3.5 Summary of faults and problems (as above)

4.0 Lessons and advice

• 4.1 Documentation standards: What did you observe about the changes in the S2S documentation standards over the semesters? What are your main reactions to the documentation standards thus far? (It would be worthwhile to look at the current semester's documentation standards in order to compare what you encountered in these reviews to what your team will be using this semester.)
• 4.2 V&V approaches: Compare and contrast the approaches reflected in the VVPs and VVRs of the two products that you reviewed. Discuss the effect that these efforts seemed to have on the quality of the final products.
• 4.3 Lessons: Discuss any other themes in what you have learned while doing these reviews. These lessons can be related to teamwork aspects you may have noticed as well as to the product development. In particular, point out lessons that can help your team in the project work this semester.
• 4.4 Advice: Give at least three pieces of advice that will assist future teams (including those from this semester) in avoiding problems or in repeating successful decisions.

---

Guidelines for this assignment

Dr. Almstrum will assign each student two projects, which she will list at the URL <URL>.

Keep the following points in mind as you do this report:

• References to your products must use the S2S codenames, since these are unique and thus unambiguous.
• This assignment is not intended as a time-consuming endeavor. Spend only enough time exploring each project to get a good feeling for it and to be able to answer the questions.
• If a project is incomplete, do what you can and note what is missing.
• While the work and writing must be your own, you may discuss your investigations with others who are working with the same project. If you choose to discuss a project with others, each of you must explicitly acknowledge such discussions in section 1.0 of your report. This collaboration may not include sharing of the written results.
• If you wish to use the services of the Undergraduate Writing Center, you are welcome to do so. You need not acknowledge this form of assistance.
• Additional resources to assist you in your writing are given at the URL http://www.cs.utexas.edu/users/almstrum/cs373/general/write-resources.html.
• While it is fine to use tables, figures, and bullet lists to help organize the material, do not use these mechanisms to the exclusion of the required prose. Any tables or figures should enhance, rather than replace, the discussion. Ensure that you introduce each table, figure, or bullet list from within the text.
• The information in your report will help in planning for further refinements of these S2S projects. It is important that you make your report complete and accurate.
• Organize the paper to make it easy for us to find the parts. Break the entire paper into labeled sections, using the numbering and headers given in the content description.

---

Layout and Writing style

• Prepare the entire assignment as a single nicely formatted web page.
• Your source HTML should be clean and readable; this is one aspect of the evaluation.
• We strongly recommend that you avoid using tools that introduce massive quantities of ugly and unnecessary HTML code. Use a tool like tidy to ensure that the final layout is clean. [Because the reviews will be compiled into summary pages, any extraneous HTML code makes this editing much more difficult.] Some suggestions of tools that can produce relatively clean HTML:
  • Netscape Composer
  • Adobe's GoLive
  • FrontPage can be customised to emit non-Microsoft HTML
  • A text editor along with a WYSIWYG tool can provide finer control.
• We have provided a template you may choose to begin from at the URL <URL>. To download the source file, you can use the "save as source" option from your browser. If you use the template, ensure that you change "Student Name" to your first and last name and switch out all references to the dummy projects and place-holders for the true references.
• Do not post your report on your web site. This will help to prevent unauthorized collaboration.
• Pay particular attention to writing mechanics, for example:
  • Issues of grammar are important in this report (in this and in all of your writings this semester!).
  • Use complete sentences.
  • Avoid passive voice. Students tend to overuse this form, which is most effective if used sparingly. Active voice makes for more compelling reading.
  • Spell-check your report before you submit it.
  • In general, do not use abbreviations.
  • Be specific in referring to the team, the project, etc. For example, many students use pronouns without a clear referent, which leads to fuzzy writing.
  • Do not repeat the questions we have asked here within your paper. Instead, use headings to demarcate each part and ensure that your introductory remarks make clear the context of the section.
• Remember that the appearance of your paper will also be evaluated. Watch spacing and indentation, since this dramatically affects readability.

• Err on the side of simplicity with formatting and layout.
• Use tags such as headings and horizontal rules to enhance the layout.
• Include a relatively compact opening banner at the beginning of the file. This should include your name, the course number and name, the title of the assignment, and the date.
• For assistance in web page design and related concerns, see the CS373 web resources page at http://www.cs.utexas.edu/users/almstrum/cs373/general/web-resources.html.

Length of answers

How long --or short-- should the discussion in each section be? In general, each part should be "long enough" to properly address the issues: too short and you won't cover all of the points satisfactorily; too long and you may be rambling, rather than getting to the issue at hand.

The portion of the report on each product should be about two to four printed pages in length, for a total of four to eight pages (the template is about two pages in length). You may exceed the maximum length if necessary to accommodate your use of tables or other supplemental information that supports the written part of the report. The length will also depend greatly on the browser and printer you use to print out your final report.

Submitting the assignment

Electronic submission of your report

• Name the file "CS373w1_Last_FM.html", where "Last" is replaced by your last name and "FM" is replaced by your first and middle initials.
• Do not post the file in a publicly accessible location.
• You need not send an email to Dr. Almstrum; the Blackboard submission suffices.
• The electronic version is due by 8am on the due date.
• You will submit your completed file, named as described above, via Blackboard's dropbox feature. There is a Blackboard tutorial on using the dropbox at http://www.utexas.edu/cc/blackboard/tutorials/Dropbox/dropbox.html. The steps are as follows:
  1. Enter the Blackboard area for CS373.
  2. Click on the Tools button along the left side of the screen.
  3. Click on the Digital Drop Box link.
  4. Click on the Send File button. (*** Be sure to click Send File rather than Add File ***)
  5. Enter the title "Your Name Writing Assignment", where "Your Name" is replaced by your first and last name.
  6. Click the Browse button.
  7. Select your file and click the Open button.
  8. Click the Submit button.
  9. Confirm that the file was sent, click the OK button. (You can print out this page as a time-stamped receipt.)
  10. Your Digital Drop Box will now display with the new file 

Hard copy submission of your report

• The hard copies of your writing assignment are due by noon on the due date.
• Take time to check the hardcopy before you hand it in to ensure that the printed layout turned out well. This simple step can allow you to correct preventable fiascos with indentation and spacing.
• Bring three (3) hard copies to class on the due date. You can also drop your copies off during Dr. A's office hours (11am to noon in TAY 4.118) or drop the copies in the homework box in the breezeway of Taylor Hall.
• In printing the document, be sure a "running header" appears on every page (this includes your name, the page number, and the file name / URL).
• IMPORTANT: Do not use the departmental machines to make multiple copies. Instead, print one copy and then use a copier to make two additional good quality copies.
• If you cannot print a running header, then handwrite at least your name and the page numbers on every page after the first.
• Ensure that your assignment is readable -- no two-up formatting, no micro-fonts.
• Staple each copy.
• Do not enclose the assignment in any kind of folder or plastic sleeve.

---

Grading criteria

Content (50%)

• Your results should be satisfactory within the constraints of the limited timeframe and your current ability to cruise the Web and use Unix. Even if documents are missing or a project cannot be run in full, you should make constructive statements based on what you can study about each project.
• Ensure that you support any assertions you make with evidence or explanation. For example, it is insufficient to simply say "The quality was good." Explain why you felt the quality is good, perhaps using terminology we have discussed in class or that you have read in the assigned articles.
• Each of sections 2 and 3 will be evaluted by one of the two TAs. They will consider the completeness and accuracy of each subsection, as well as of the overall section.
• Sections 1 and 4 will be evaluated by Dr. Almstrum.

Formatting and following instructions (20%)

• Both the electronic and the hard copy versions should be organized and submitted as described in this assignment.
• The formatting of the web page should make it easy to read and understand both in the displayed formatting and in the source HTML code.
• Dr. Almstrum will evaluate this aspect of the grading assignment.

Writing mechanics (30%):

• Grammar and spelling should be correct.
• The writing style should make your paper readable and easy to follow.
• The writing feedback from earlier semesters may prove helpful, for example:
  http://www.cs.utexas.edu/users/almstrum/cs373/fa03/write-feedback.html
• Writing mechanics will be evaluated by the two TAs and Dr. Almstrum on their respective sections.

Resubmission

• We will offer a resubmission opportunity that will allow you to improve your grade if any aspects of the initial version turn out to be deficient. The regrading will consider the portions you wish to have regraded, as well as the overall improved status of the revised report. The regrade will allow students to recover as much as 80% of the points they lose due to deficiencies in the first submission.