next up previous contents
Next: 13. Progress Report Up: CMPE 185 Workbook Previous: 11. Algorithm Description   Contents


12. Document specifications

12.1 Goals--three purposes for document specifications

A document specification contains several parts: a description of the audience(s) for the document, a detailed outline giving the structure and contents of the document, and a work plan showing who is responsible for each part of the document and what the deadlines are for completing each task. For large documents, there may other managerial information, such as number of pages allocated for each section, graphics budgets, printing costs, and so forth. We do not expect you to produce this level of detail in your document specification.

In the workplace, formal document specifications serve three important functions: economy of effort, work planning, and writing organization.

12.1.1 Economy of effort

First, document specifications are used to help you reduce the amount you have to write. When you are requested to write a major report, quite often you will be told something like, ``Do a draft and then come see me with it.'' After talking with your boss, you will have to revise the draft completely so that it will have in it what the boss really wants, since he/she hadn't thought about the project carefully until reading your draft. You can often save yourself (and your boss) much work if you write a detailed document specification instead. A document specification is much easier to create, change, revise, and add to than a draft is.

12.1.2 Work planning

The second major function of a document specification is work planning. This can mean either budgeting your own time, or, in large formal reports, distributing the work among many people. Multi-author writing is probably the most common form of workplace writing. The more you know about the specification, the more likely you are to get only your fair share of the writing and no more.

For the purposes of the class, the document specification will serve to distribute the work between you and your partner. You should bear three things in mind in dividing the work: even work load, respective areas of expertise, and getting things done in the order that you need them. These points sound obvious, but achieving a fair distribution of the work is not always easy. It involves keeping to a schedule, for one thing, and staying in close touch with your partner, for another.

12.1.3 Writing Organization

The third major function is the organization of the report itself. This function is discussed in Section 12.3.2 below.

12.2 Audience assessment

As with the proposal, we are the supervisory audience for this document specification. However, we are not the audience for your final report. Don't get confused on this point. If you are writing user documentation for software meant to be used by first-year students in a chemistry lab, they are your audience, not us. For more on this issue, refer to the final report assignment (Chapter 14).

The document specification you are writing is a working document, meant to allow us to help you with your project. The fuller and more complete your document specification is, the more we can help you.

A tool that is useful for doing the audience assessment for your final report is a user matrix. Each row of a user matrix corresponds to one group of readers for the final document, and each column corresponds to one topic in your report (perhaps a section heading). Each entry in the matrix indicates how important that topic will be to that group of readers. For example, in hardware documentation the parts list may be essential to Manufacturing, but useless to Marketing.

You can use any quantification scheme you want for the entries of the matrix, but there is no need to get fancy. In most cases, a single bit (needs to read this/doesn't need to read this) is sufficient.

Before writing your document specification, try to make a list of the different readers you expect for your final project. At the very least, you should include your classmates, as they will be the audience for your oral report. If your project is the final project for some other class, you should include the instructor for that class and students who are planning to take the class.

Once you have the main topics of your report identified, you can use the user matrix to help you order them. Try to put the most important information first--the things that everyone needs to read should be near the beginning, and the things that only a few readers need later or in separate appendices. If possible, try to arrange things so that most readers can read a contiguous chunk of the report, not having to skip irrelevant pieces.

The user matrix is an important part of the document specification, so please include it in what you turn in.

12.3 Writing process--document specifications

12.3.1 Outlining is organizing

Some of the material that follows is also found in the final project assignment. The material will be repeated because it is about organizing technical reports. Here the stress will be on the detailed outline in a document specification as a management tool for writing technical reports.

Outlining is organizing. This is a point sometimes obscured in presentations that get bogged down in what type of number to use for the third innermost nested subhead. We assume here that you can figure out how to do that kind of thing in a clear and consistent way, and concentrate instead on the underlying principle involved--organization of technical reports, and organizing the process of producing them. Organization, of the writing process and of the report itself, is the basis for two of the three major functions of document specifications.

In preparation for this assignment, read Chapters 12 and 15 in Huckin and Olsen, where a somewhat similar scheme for organization is discussed. Their scheme differs mostly in detail, not in principle. The process and the product are the same. If Huckin and Olsen's scheme makes more sense to you, then use that one.

12.3.2 The basic tripartite structure of a formal report

The outline that follows is the core of the one presented in the final project assignment (Chapter 14). It displays the basic tripartite structure of most technical reporting. This outline is very general, and very abstract, and is designed to show you the internal structure of virtually all technical reporting, not provide you with headings for your own document specification. These headings used here show internal structure, but they have no technical content.

Your headings must contain the primary content of your report. Generic headings, like the ones used here, will not be acceptable.

  1. Front matter Each of the sections of the front matter should include a brief version of your problem statement and your recommendation, if appropriate. (See parts 2.2 and 3, below). Most documents use only two or three sections in the front matter--it depends on what you are writing.

    Executive summary. In the workplace, your recommendation is the most important part of an executive summary, and should immediately follow a brief statement of the project or problem.

    Abstract. It is unusual to have both an abstract and an executive summary, because both serve essentially the same function in different types of reports.

    Preface. A preface usually contains a description of the target audience and intent of the document, and a list of acknowledgements for contributions made by people other than the authors.

    Introduction. An introduction is used to explain the background or significance of the main part of the paper.

  2. Technical Discussion

    Problem Statement.
    What was studied, designed, built, or investigated
    What the purpose of the study, design, or investigation was
    What you found out
    Full explanations for Heading 2.1, above, that is
    How you did it, including, as appropriate, tests, procedures, methods, materials, processes, equipment, programs (if they're short, otherwise leave them for the Appendices)
    What happened, including, as appropriate, test results, data collected, full description of design(s), procedures modified, processes completed
    Your interpretation of your work

  3. Recommendations (especially important in the workplace: finding out what to do is why they have you do the report)

    Description of solution to problem or proposal for change
    Benefits to the company
    Rejected alternatives

    For research reports, this section is often titled ``Future Work'', giving recommendations for new ideas to pursue. A design document may end with suggestions for improvements to make, a marketing plan, or whatever else needs to be done with the design. User's documentation will often end with suggestions for further reading for those interested in more details.

12.3.3 Organizing the work and the writing

The sequence described in Section 12.3.2 is typical of the sequence of topics in a technical report. It is not, however, the sequence in which the report is written or the work is done. In terms of organizing work and writing, this is the crucial point: the work, and the writing, begins in the middle!

Everything begins in the middle because, if you look at part 2.2, you will see that this section deals with things that engineers actually do. Here you are working with ideas for your project based on your proposal, which, once you have done the work and know how it really came out, you use as a basis for writing part 2.1, the Problem Statement.

The work in part 2.2, and the writing that goes with it, are the first things that you and your partner need to divide up. Divide both work and writing. For this paper, you may very well be documenting an already completed project, in which case you will be dividing just the writing, but be sure to go over each step of the project together, so you both agree on what you think was done. What documentation actually exists almost certainly amounts to notes for part 2.2 of the Technical Discussion, so work with them accordingly.

Thus, the first writing that gets done covers the areas in part 2, Technical Discussion. Your interpretation of your work (part 2.2.3), leads to the next section normally written: Recommendations (part 3). Once you have this figured out, you can go back and write the Executive Summary (part 1), because you now know what the work you did was designed to find out or produce, namely, the answer, the solution, the usable design, which provides the basis for your recommendation.

Since this is what you are being paid to figure out, it goes right up front in the Executive Summary, where your employer can see it!

12.3.4 Which projects do not use the Tripartite Structure?

The outline in Section 12.3.2 is the basic tripartite structure of formal reports. This structure is especially appropriate for documentation of your own research projects, what we are calling here design documents. However, if you are doing user documentation, your format is likely to be more like the formats used in the naive-user documentation assignment (Chapter 8). If you're doing user documentation, review Chapter 8, re-read your notes from the guest lecture, and take a good close look at UNIX for Luddites again.

12.4 What to turn in

The document specification should be written as a memo to us. Leave plenty of white space, so we have room to make suggestions and amendments.

You and your partner should turn in to us as full and as explicit a document specification as you possibly can--the Technical Discussion section should be particularly detailed. It should also identify, item by item, who is doing and writing what.

By now, your project should have a title. Use it on your document specification.

Turn in your user matrix. We'd like to see who you are writing for, and what you think they need to know.

Turn in your project proposal again with the document specification. We want to see that your document specification matches your proposal--if it doesn't, you should have an explanation of the discrepancies, perhaps even a modified proposal. We cannot be expected to remember the details of all the projects being done!

next up previous contents
Next: 13. Progress Report Up: CMPE 185 Workbook Previous: 11. Algorithm Description   Contents

Kevin Karplus
Computer Engineering
University of California, Santa Cruz
Santa Cruz, CA 95064

HTML version created 2003-02-13