"The writing that engineers and scientists do can be legally crucial, ... . Your writing constitutes part of the legal record of a project and might end up as evidence in litigation. Thus, part of your job responsibility as an engineer or scientist is to make your writing precise and to keep accurate records of what you've written."Above quote from Woolston, D. C., P. A. Robinson, and G. Kutzback, Effective Writing Strategies for Engineers and Scientists, Lewis Publishers, Inc., 1988, p. 151.
Mathes and Stevenson in their Designing Technical Reports: Writing for Audiences in Organizations, Second Edition, Macmillian, 1991, pp. 455-469, present six basic precepts that engineers and scientists need to observe in order to protect their readers, their company, and themselves in the legal context. These precepts are as follows:
These basic precepts apply to all your written documents - letters, memoranda, laboratory notebooks, Project Notebook as well as technical reports. You never know what might be used in litigation.
In industry, the Project Notebook might be a three-ring binder of bound pages. In this course, each team will use an on-line Wiki in which the team can keep their daily technical and rhetorical work. It allows your team to keep precise and accurate records of what each member is doing. Because no one can remember everything precisely, a written record at the time something happens is the only way to insure accuracy of the event. Obviously, computer scientists have an ethical responsibility to keep written records that are precise and clear in their Wiki.
In order to develop good documentation habits, you must maintain the team's Wiki daily. The requirements for the Wiki are described below. The expectation is that you will develop a daily habit of maintaining the Wiki. You will record such information as literature reviews, bibliographical information, ideas, design notes, minutes to team meetings, memos, drafts of reports, critiques of reports and reports. Since the primary purpose of the Wiki is to aid the team, maintaining an accurate representation of the team's communication is in your best interest.
Assuming you develop a daily habit of placing information in the Wiki, you will be able to write precise and clear technical reports because all the necessary information will be at the team's disposal.
How to Log on to Wiki?
The course will be using Bucknell University's Confluence Wiki. To access the Wiki, point your web browser at http://confluence.bucknell.edu and click the "Log In" link in the upper-right hand portion of the screen to login to the system. The login is the same user name and password that you use to access a Windows computer.
Only your team members and Professor Hyde can access your Wiki Space.
What Sections are Required?
The Wiki must have the following six Section Headings in this order:
What Must Be In Wiki?
The contents of each section of the Wiki is specified below. The Wiki will automatically keep track of the date and the individual who posted the document. In industry, you probably will be required to date and initialize any item placed in a notebook.
The Administration section includes an introductory page on the Project, the names of all the team members, their telephone numbers, campus addresses and email addresses.
This section contains all the minutes of the team's meetings in chronological order.
This section contains all the team's correspondence including memoranda, team assignments and reports in chronological order.
This section contains links to web sites pertaining to the Project, articles, reviews of articles, and bibliographic information.
This section includes notes on design ideas. Also, this is where material should be placed if it does not fit in the other sections.
This section includes links to design documents associated with a program, program listings, test suites, and any assessment of the program, e.g., performance data.