README File¶

The goal of a README file is to describe what the folder contains. It's purpose is to be USEFUL! It should explain what is in the directory and, as needed, explain why or how to use it. This way others do not have to open every file to figure out what is in each and what they are for. Although file names should be meaningful, any that are not should be commented on in the README. Don't just restate the folder name in words in the README - explain it instead!

A useful README should indicate:

• how to get started with the material in that folder, for example which CAD model to open first or which file should be read before the others. A good README is somewhat of a 'getting started' guide to that folder.
• The purpose of the directory, i.e., type of information stored.
• Software used and versions
• List of sub-directories and files stored.
• Where / how to get started using the folder's contents. For example if there is a program in the folder, quick start instructions on how to run it would be very helpful in the README.

EXCEPTIONS:

• Some software development tools generate many files and folders as part of 'compiling' or 'building' an application. These folders are dynamic and do not require README files.
• Some software applications may process entire folders of data at a time. The presence of a README file may break the code. In these cases, the README can be left out of that data folder but the README for the folder one level up should provide the explanations.

Generally README files are plain text files NOT WORD documents. That way they are readable even from a terminal / DOS session and don't require special software to access. A template (README.txt) is available. Please AVOID using Markdown format as that is NOT pre-installed on our computers! Yes, we know it provides very nice looking output. We know that it's free to download one or more tools to use it. But we already have a tool that is pre-loaded on our PC's and produces nicely formatted output. It's called Microsoft Word! Use plain text files for README files. If you need more, the information probably should be in the wiki! Or you really need some sort of user manual which would be best created in Word due to its full formatting capabilities.

A sample README file for “Final Report” is shown below. If different files were created using different versions of the software (for example Microsoft Word 2013 vs. 2016 - then that needs to be noted on a folder by folder or file by file basis. Be sure to include the operating system and it's version as some teams use things other than Windows. Avoid fancy indenting - this is a plain text file and multiple indents quickly make the file hard to read.

This directory contains project reports.

Software Used:
    Windows 7, Ver. SP1
    MS Word, Ver. 2007 (.docx) 

Sub-directories:
Dynamic Loading – all measurements made on the INSTRON for the dynamic loading test
Strength vs Temp – all manual measurements for the strength vs. temperature test

Files:
README.txt – This file (Text file)
Instron Test SOP.docx - Standard Operating Procedure for tensile testing
analysis.m - main MATLAB program that accesses the test data from the sub-directories
method_xyz.m - called by Analysis.m to use the XYZ algorithm
   :