In today's technical workplace, accurate, clear, complete documentation plays a critical role in effective project management. Project documentation helps to ensure the accuracy, credibility, and validity of the information communicated during the project. It provides a record of the events, activities, and decisions related to a project.
In this module, we'll explore the development of documentation for a project from inception to completion. We'll focus on these topics:
identifying and focusing a topic
gathering and documenting information
preparing proposals
monitoring project progress
summarizing information
preparing reports
First, we'll look at defining and narrowing the focus of a topic and the need to analyze the audience and purpose. Then, we'll discuss gathering information through various research methods, evaluating the relevance of the information and its sources, and incorporating it into our writing. Next, we'll examine how to propose ideas and plan to investigate them in a formal document, the planning proposal. We'll also look at documents to monitor the progress of the project and to record what happens during meetings. We'll focus on the research results and on evaluating, refining, and organizing them into an effective report. Finally, we'll discuss the designing, writing, revising, and packaging of the report and its components.
Now let's look at some of the most important concepts of technical writing we'll examine in module 2.
After completing this module, you should be able to:
How do you get from an initial idea to the final product for a project? What steps do you follow to develop, refine, and focus your ideas? The diagram shows the steps in the development of project documentation. We'll explore each in greater detail and examine documentation needs throughout the life cycle of a project. Besides reading the stage-by-stage description of this process, you can also click on any of the boxes to go to the corresponding step in the discussion.
The Project Documentation Process
Click on any of the stages below to go to the discussion of that stage.
Note: To print this diagram set your printer settings to landscape.
The life cycle of a project begins with the gist of an idea, which you then need to define and expand into a fully developed topic as the project proceeds. The section on "Planning" in Chapter 3 of Markel and unit 3 of the course guide describe how to develop your topic and narrow its focus.
After defining your topic, you must analyze your audience and determine your purpose so you can identify your information needs, develop your approach, and organize your information. As you recall from module 1, the primary audience for project documentation is usually decision makers, frequently some level of management or someone with decision-making authority. This audience uses the documentation to increase knowledge, gather information, stay informed, and make decisions. The secondary audience for project documentation can include coworkers, managers in other areas, and others interested in the project.
Your purpose helps you to identify concisely and clearly the topic you are investigating. Determining your purpose also enables you establish project boundaries, or the limits within which you plan to concentrate your investigation. These limits define the scope, or the extent, of the topic. Markel's chapter 19 discusses analyzing your audience and purpose for a report in the section, "A Problem-Solving Model for Preparing Formal Reports." You can apply the questions and information from this section to other project documentation.
Once you know something about your audience and purpose, you can conduct some preliminary research to learn more about the topic. You can use a variety of research methods for gathering information. Primary research methods, such as surveys, interviews, written inquiries, and field observations, are used to create or discover new knowledge. Secondary research methods are used to gather information about research that has already been published and reviewed. You can use indexes, abstracts, and online databases in conducting secondary research.
In a technical environment, you use a combination of primary and secondary research methods to gather information. For instance, suppose you must give your company's management information to help them decide whether to build a corporate Web site. What type of research methods would you use? You'd use a variety of resources to research this topic, including
an Internet search of competitors' Web sites
interviews with competitors about their Web sites
interviews with Web designers about potential content for a Web site
a review of current technical literature about implementing a Web site
Chapter 7 of Markel and unit 3 of the course guide describe the various primary and secondary research methods.
As you gather material using secondary research methods, paraphrase and summarize the information as much as possible. Use direct quotations only when you want to present the author's specific phrasing or add credibility and authority to your writing. Chapter 7 of Markel describes a process for paraphrasing and for summarizing information, and unit 6 of the course guide describes the latter.
In addition, you must evaluate your sources of information to determine whether they are accurate, unbiased, comprehensive, current, and clear. Markel discusses how to evaluate information sources in the "Conducting Secondary Research" section of chapter 7.
As you review and extract information from each source, write the information needed for its reference. Use the format associated with the style guidelines for your discipline. In this course, we use the style and conventions of the Modern Language Association (MLA). MLA style guidelines are presented beginning on page 676 in the "Appendix: Reference Handbook" of Markel, in the "Documenting Your Sources" section of unit 3 of the course guide, and in the "MLA Documentation" section of the Hacker reference.
At this point, you've analyzed your readers and their needs; identified your purpose, scope, and approach; and gathered some preliminary information about your topic. Before proceeding further with your ideas, you should present this material formally to your audience in the form of a planning proposal.You can use this document to seek approval from your audience, such as your manager, supervisor, or teacher, to study the topic further.
A planning proposal presents a topic that is an issue or problem along with possible ideas to improve or solve the problem. A planning proposal can include this information:
description of the purpose and scope of your topic
description of the issue or problem that provides sufficient background information for your reader to understand the issue
discussion of your proposed ideas for change and their benefits and limitations
plan of action that describes your research methods, schedule of research activities, time estimates for completing these activities, and packaging of the final product with a preliminary outline
description of the physical, financial, and personnel resources needed to complete the project
Markel's chapter 17 and unit 4 of the course guide discuss proposals in greater detail. Unit 4 focuses on the planning proposal and how to construct one. It also provides several examples of research schedules.
For an example of a planning proposal developed for a COMM 393 project, see the Planning Proposal Example.
Once your project is approved, you can execute the plan of action discussed in your planning proposal. As your project proceeds, you need to keep the sponsors, management, and others interested in the project informed about your progress. Progress reports describe and summarize the activities of the project—what work is completed, remaining to be done, and in progress. They indicate whether the project is running smoothly or having difficulties and describe the ways situations occurred as well as how they are being handled. These reports are written periodically during the course of the project. The "Writing Progress and Status Reports" section in Markel's chapter 18 and the "Monitoring Your Progress—Progress Reports" section in the course guide describe these reports in further detail.
For an example of a planning progress report developed for a COMM 393 project, see the Progress Report Example.
You may also attend and possibly host meetings during your project. These meetings should be documented in minutes, which are valuable sources of information. Minutes detail who attended the meeting, when it occurred, what happened, what decisions were made, what actions occurred, and who will complete what actions before the next meeting. The "Writing Meeting Minutes" section in chapter 18 of Markel and the "Recording What Happens in Meetings—Minutes" in the course guide discuss minutes more fully.
As you gather more information and learn more about your topic, you must evaluate your research findings and interpret your results. Your results may support your original ideas, not support them, or indicate that you need to modify them. Your ideas will evolve as the project continues.
In addition to interpreting your findings, you must also organize them logically and effectively. Markel's chapter 8 describes how to do so and presents basic patterns of organization. The information in this chapter will help you organize your analytical report.
Once you've interpreted your findings, you're ready to draw conclusions. You derive these from your purpose and initial analysis. They represent your evaluation of the ideas and reflect all perspectives on the issue or problem.
Recommendations should flow from your conclusions and urge specific actions based on the conclusions. Markel's chapter 19 and unit 5 of the course guide discuss the process of evaluating and interpreting research results, drawing conclusions, and making recommendations.
After gathering and interpreting your information, drawing your conclusions, and determining your recommendations, you can design, organize, and compose your report text. Develop a consistent design that enables readers to locate information easily and that projects an inviting, professional image to readers. Organize your report to meet your purpose and your readers' needs and expectations.
Begin writing at whatever point you feel most comfortable. You don't need to start at the introduction! Review your project documentation, such as the planning proposal, to see whether you can incorporate any parts into your report. Markel's chapter 19 and unit 5 of the course guide give more guidance about writing the text of the report.
A formal report consists of a standard set of components commonly recognized in a technical environment: a letter of transmittal, title page, table of contents, abstract or executive summary, text, glossary, bibliography or works cited, and appendices. Chapter 12 of Markel and unit 5 of the course guide discuss these components in more detail. Abstracts and executive summaries are described in unit 6 of the course guide.
For an example of an analytical report developed for a COMM 393 project, see the Analytical Report Example.
Review unit 6 of the course guide to learn different ways to use summarized information. For example, you can document by using an abstract with summaries as information capsules. In today's fast-paced technical environment, information capsules are a handy option for giving readers an overview of a topic in a condensed format.
During this module, you have three writing assignments in which you begin carrying out the steps in the project documentation process. You saw an example of the first of these, the audience analysis, in module 1 when we highlighted the importance of audience as one of the central concepts of technical writing. You'll write one of these during module 2, as well as a planning proposal, in which you lay out what you want to analyze, and a progress report, in which you describe the status of your project as you implement your plan.
The final product of the technical writing process, the analytical report, requires a fair amount of time. For this reason, you won't be asked to turn it in until the end of module 3.
You'll find specifics about each of these assignments in the Lesson Guide and in Quick Access - Assignment Files.
Let's look first at an example of a planning proposal in memo format written for the same COMM 393 project as in module 1.
Here is an example of a progress report written for the same COMM 393 project.
At last we come to the final product, the analytical report written for the same COMM 393 project. Perhaps the student threw a celebration party after turning it in! She deserved it, because she received an A for her good work. In fact, the work she did on this class project was one of the main reasons her future employers hired her.
Project documentation contributes to successful project management. It tells the project sponsors, organizational members, management, and others interested in the project about it and its progress, strategy, results, and conclusions. The documents discussed in this module—planning proposals, progress reports, minutes, analytical reports, and summaries—inform your readers about the project from its inception to its completion. Thoroughly investigating the topic and using a variety of research sources also enhance the accuracy, credibility, and validity of the documentation.
In the next module, we explore the design of documents and the use of graphics in them. Document design is becoming increasingly significant in today's visually oriented society. Graphics also play an important role in communicating information in many technical documents. We'll also look at two other types of technical writing, instructions and technical descriptions.