next up previous contents
Next: 15. Poster presentation Up: CMPE 185 Workbook Previous: 13. Progress Report   Contents

Subsections


14. Final project

14.1 Goals--formal report writing

The main goal of this assignment is to learn how to write a formal report in several defined steps, each of which is a separate sub-assignment. You will have done, in sequence, the Proposal Memo, the Document Specifications, and the Progress Report. This chapter will discuss the final form of the Final Project. Some of what is covered here was also discussed in the document specification assignment, although largely from the perspective of organizing the writing process. Here we will be discussing the sequential organization of the report itself, and the reasons for it. The relevant sections of Huckin and Olsen are Chapters 12 and 15 and Sections 9.3 and 9.4 [HO91].

Your final project can be a design description (for a design you did yourself), a library research paper, a formal proposal for a future design project, or user documentation.

14.2 Audience assessment--choose your own

You must define your own audience for this project.

If you do a design description, your audience might be the management of your company, or one of your professors, or students who will be doing similar design projects in future years. Writing for future students is probably the easiest, as you can have a better idea what things they will be interested in.

For a library research report, your audience might be the readers of a magazine in which you intend to publish the survey article. (If you pick this sort of audience, specify the magazine or journal you're aiming at.)

If you are doing user documentation for any of the things suggested on our project list, think carefully about the real audience, which differs considerably from project to project--some are for beginning students, some for advanced students and professors. Remember that the audience is not the instructor for the writing class, nor the professor you have contacted about the needed documentation.

Keep in mind that for the oral report based on this assignment, your audience will be the class.

14.3 Writing process

14.3.1 Writing the Report

We will go over the elements of a formal report, and the reasons for them, in class. The tripartite structure discussed below is especially appropriate for documentation of your own research projects, what we have been calling design documents in class. If you have any questions as you are working, refer to this chapter or to Huckin and Olsen, Chapters 12 and 15 [HO91], for the structure of formal reports.

Some moderately useful stuff for library papers can be found in Chapter 16 of Huckin and Olsen, but you should also consult one of the other texts on reserve for this sort of paper. McGuire and Putzell [MP88, Chapter 12] and Trzyna and Batschelet [TB87, Chapters 3 and 4] may be useful. Also, your experience with the poster presentation is relevant. Look over Chapter 15 again, as well as your notes from the guest lecture by the reference librarian.

If you are doing user documentation, as we mentioned in the document specification assignment, your format is going to be more like the ones used for naive-user documentation, so review Chapter 8 of this workbook. Also, the section entitled ``Manual Writing'' in Trzyna and Batschelet [TB87, Chapter 12, pages 281-297] has a good deal of useful general advice and some helpful examples.


14.3.2 The tripartite structure of a formal report

As discussed in the documentation specification assignment, what follows is intended to be general, to provide an idea of the basic components of a formal report. It is not an outline for you to fill in, especially since some of the headings name functions, rather than being titles for sections. You will have to choose which things you need to include. You are unlikely to need all four items in Section 1, for instance, and you may or may not want to include a letter of transmittal to the contact person for your project. See pages 220-223 of Huckin and Olsen for an explanation of letters of transmittal [HO91, Section 11.3]. You might have to include a quite substantial appendix or supplementary section, depending on the project.

Front Matter
Letter of transmittal, title page, contents, list of figures, list of tables, and acknowledgments.

1
Executive summary, abstract, preface, and introduction.
See Section 12.3.2.

2
Technical Discussion
See Section 12.3.2.

3
Recommendations
See Section 12.3.2.

Appendices and Attachments
bibliography or list of cited works, tables, documents, data, source code, maps, letters, testimonials, brochures, resumes, index--depending on what you are writing. Usually the list of cited works (labeled References) comes first, and the index comes last. The others come in whatever order is appropriate, and are called Appendices.

Versions and modifications of this outline may be used for your final reports. Modify this outline to suit your project--don't force your paper to fit the outline. You may find that the main body of your report divides naturally into four or five parts instead of three; that's fine, but ten parts would not be fine. Be wary of subdividing into too many parts at one level, as that indicates that you haven't properly grouped related subjects together.

Most important, give each of your sections meaningful headers, not the generic headers we used in the outline.

The outline above is a guide, not a rule. Compare it with the schemes in Huckin and Olsen, Chapters 12 and 15. There are similarities and differences, but the underlying ideas are consistent.

14.3.3 Explanation of Tripartite Structure

The outline in Section 14.3.2 is the basic tripartite structure of formal reports. The three parts of the tripartite structure are the beginning, the middle, and the end, not surprisingly. As we discussed in the outline assignment, starting down in the bowels of the report, the Technical Discussion has three parts: 2.1, 2.2, and 2.3. But the Technical Discussion itself is the middle, or the body, of a larger structure, where the beginning is part 1, and the end is part 3.. This whole piece, parts 1-3, is the main body of your report and forms the ``middle'' between the Front Matter and the Attachments for the entire report.

Besides being organized in nested ``middles'', between beginnings and ends, you will notice that the document progresses serially from the simple to the complex, and repeats itself in increasingly complex ways at least once, and more likely twice. For example, the simplest text is going to be in the executive summary, and this may be as far as some management readers will get. The most technical material may very well be a long list of design specifications in an appendix, and may not even be recognizable for what it is by some readers.

The purpose of this feature, the organized and repetitious progress through ever more complex explanations of the same thing, is that technical reports have many audiences with many purposes. The management reader is concerned with allocating resources, both money and personnel, and planning for the organization as a whole. The executive summary tells her/him what projects have become feasible, what problems have been solved, what new products are possible. This is the kind of information on which management decisions are based.

The production engineer who will implement the new design, however, may very well skip most of the beginning material, go to the heart of the technical discussion, read it quickly so she/he will understand what's going on, and then move on to the detailed specification of the new design. On the other hand, another engineer with a similar design problem may consult only the technical discussion, looking for ideas for solving her/his somewhat different problem.

Overall then, organization of a technical report in this fashion serves the needs of all the audiences who will consult the report.

14.3.4 A note on page numbering

Every page after the title page must be numbered, and your table of contents must list the page numbers for at least the major sections of the report. There are many popular styles for page numbering, and you may choose whichever you like, as long as you use it consistently.

Many computer scientists prefer a page numbering that starts on page 1 (page 0 is the title page), and continues sequentially until the end of the report. This style is easy to generate with word and document processors, and is easy for the reader to understand. When printing on both sides of the paper, the odd-numbered page is always the right-hand page, and the even-numbered page the left-hand page.

The more traditional scheme uses lower-case Roman numerals for the front matter, and starts page 1 at the beginning of the body, numbering sequentially from there. It is a holdover from when books were typeset by hand, and the front matter was often not written when the main body was being typeset. Some traditionalists still insist on this scheme, even though the technical motivation for it has almost disappeared.

One compromise scheme sometimes found in frequently modified documents (such as computer manuals) is to number separately within each chapter, so that Chapter 1 starts on page 1-1, Chapter 2 on page 2-1, and so forth. In traditional formats, appendices are often numbered this way, with Appendix A starting on page A-1. Separate numbering for each chapter allows updating a manual by replacing one chapter, rather than replacing the entire manual.

14.4 Citing your sources

It is absolutely essential that every idea you present in your paper can be traced back to the original source. You should provide a citation for every idea--not just direct quotes and paraphrases.

A citation generally refers to the immediately preceding sentence (if it comes before the period) or paragraph (if it comes at the end of a paragraph, after the final period). Providing a citation just tells people where an idea came from, and does not indicate that any quotation or paraphrasing has taken place. Providing a citation is not sufficient protection from charges of plagiarism if you copy someone else's words without making the quotation explicit.

The citations come in several different styles--I generally like square brackets around a short identifier that can be used to look up the citation in the reference list, though some people prefer numbers to alphameric identifiers, and some people prefer parentheses to square brackets. The reference list itself should be alphabetized by first author (which should be consistent with the alphameric identifiers, if you use them).

For more details about good citation formatting and style, I recommend A Handbook for Scholars [van78]. The book is well written and is a pleasure to read, despite the unpromising title.

14.5 Oral Reports

You may still be working on your draft when you give your oral report. This is an advantage; you can incorporate any feedback you get from the class in your final draft. Wise students will do their oral presentations as early as possible. In industry, oral presentations (sometimes more than one) are often given before the final draft of a report is submitted.

14.6 What to turn in

The due dates for the assignments are given in the syllabus.

Draft 1
The first draft of your project is due in class. We will work on them extensively in class that day. This session will be concerned primarily with organization of material, adequate explanation, and inclusiveness.
Draft 2
The second draft of your project is due in class. This time we will be concerned with formatting, and a host of editorial questions involving clarity of presentation and explanations. The nitty-gritty stuff.
Final
The final project is due, no later than 5:00 p.m., in Kevin's office. You will turn in the following:


next up previous contents
Next: 15. Poster presentation Up: CMPE 185 Workbook Previous: 13. Progress Report   Contents

Kevin Karplus
Computer Engineering
University of California, Santa Cruz
Santa Cruz, CA 95064
USA
karplus@soe.ucsc.edu
1-831-459-4250

HTML version created 2003-02-13