add explanation / walkthrough of machine-readable files