modify documentation to explain future-proofing and namespacing contingencies