PAHMA-835: improvements to documentation