added more details and a deprecation list to the future doc.