DOCUMENTATION GUIDELINES. Professor Pete Avitabile. Department of Mechanical Engineering. University of Massachusetts Lowell

Transcription

1 DOCUMENTATION GUIDELINES Professor Pete Avitabile Department of Mechanical Engineering University of Massachusetts Lowell 1 Dr. Peter Avitabile

2 Documentation is an important part of any project or assignment. Significant attention should be given to this often overlooked item. Documentation items addressed here are: Laboratory Documentation Analysis/Computer File Documentation Journal Documentation 2 Dr. Peter Avitabile

3 There are three main items that should always be followed when working on any project Plan what you do Do what you plan Document what you did The last item is the one that is always easiest to take shortcuts and skip over 3 Dr. Peter Avitabile

4 Documentation is the part of the process most people hate to do. But it is the most critical part of the process. Documentation leaves a trail for others to follow In many cases, it helps you to recall what you did 4 Dr. Peter Avitabile

5 Laboratory Notebooks 5 Dr. Peter Avitabile

6 Laboratory Notebooks A laboratory notebook must be Bound document Numbered pages Written in ink (pencil unacceptable) Signed by author Countersigned for authenticity 6 Dr. Peter Avitabile

7 Laboratory Notebooks In documenting a laboratory test, the main item that you should ask is Can someone else replicate the data that I collected? Is the documentation complete enough to accomplish this? 7 Dr. Peter Avitabile

8 Laboratory Notebooks Things a laboratory notebook should include Time, date, those present Procedure or test plan Equipment, model, S/N, calibration date Settings of equipment Raw data (if not on disk) Reference to where data is included on computer Logical naming scheme for files 8 Dr. Peter Avitabile

9 Laboratory Notebooks Several sample log book sheets are illustrated 9 Dr. Peter Avitabile

10 Laboratory Notebooks Title Dated & Numbered Pages Neatly written in ink Signed 10 Dr. Peter Avitabile

11 Laboratory Notebooks Equipment List 11 Dr. Peter Avitabile

12 Laboratory Notebooks Equipment Settings 12 Dr. Peter Avitabile

13 Laboratory Notebooks Raw Data with Properly Identified Change in RED 13 Dr. Peter Avitabile

14 Laboratory Notebooks Observations During Test Noted 14 Dr. Peter Avitabile

15 Laboratory Notebooks Identification of Location of Stored Computer Data 15 Dr. Peter Avitabile

16 Laboratory Notebooks Repetitive information may best be handled with a customized data form taped into logbook 16 Dr. Peter Avitabile

17 Computer Materials 17 Dr. Peter Avitabile

18 Computer Materials In documenting your computer files, the main item that you should ask is Can someone else determine what this computer run is used for? Is the documentation complete enough to accomplish this? 18 Dr. Peter Avitabile

19 Computer Materials Things to include for computer files Organized directories Date files (abaqus_run4_ inp) Main directory should have a README.TXT file that summarizes the files below Subdirectories should also have a README.TXT file to overview the files in that directory Logical naming scheme for files 19 Dr. Peter Avitabile

20 Computer Materials Things to include in files themselves Document the file with header information so that you can quickly determine the intent of the file Use comment lines throughout the file to explain the purpose of various sections Use variable names that have some physical meaning 20 Dr. Peter Avitabile

21 Computer Materials Directory structure helps locate files/runs 21 Dr. Peter Avitabile

22 Computer Materials Logical names and README.TXT files help 22 Dr. Peter Avitabile

23 Computer Materials Logical names with dates help APACHE is the hardware FIX means it was built in means it was tested 8/21/03 23 Dr. Peter Avitabile

24 Computer Materials Comment lines help define intent of file 24 Dr. Peter Avitabile

25 Computer Materials Comment lines help document portions of file 25 Dr. Peter Avitabile

26 Journals 26 Dr. Peter Avitabile

27 Journals In writing a journal, the main item that you should ask is Can I recreate the sequence of events? Is the documentation complete enough to accomplish this? 27 Dr. Peter Avitabile

28 Journals Things to include in a journal Daily discussions and meetings Phone conversations summarize key points Business cards of people related to your work Thoughts on possible new items (inventions, etc) 28 Dr. Peter Avitabile

29 This information is for your benefit 29 Dr. Peter Avitabile