add usage notes
fix variable names