improved docs - structure, and how to write scripts