Update docs to reflect changes

@astrofrog - feedback as you see needed; this will wait until the final script versions  are ready (i.e., do not merge yet!)