some docs updates which should make it easer to reuse for others