add better feedback to script and documentation

also formatting