Revamped documentation due to #2915 and #2898