update docs based on forum posts