ensure that it accurately mentions currently code capabilities, gotchas, and links to documentation (to be done after #88 and #17 )
