documentation updates

Relates: #806 (closed) Resolves: #842 (closed)

Checklist

• Commits have Signed-off-by: with name/author being identical to the commit author
• Documentation updated / NEWS entry present (for non-trivial changes)
• CI timeout is 2h or higher (see Settings/CICD/General pipelines/Timeout)

Reviewer's checklist:

• Any issues marked for closing are addressed
• There is a test suite reasonably covering new functionality or modifications
• Function naming, parameters, return values, types, etc., are consistent and according to CONTRIBUTION.md
• This feature/change has adequate documentation added
• No obvious mistakes in the code