Based on input from consulting and my own understanding:
- The current documentation is written in top-down fashion, i.e. it first talks about the cleanup strategies and only then goes into the distinction between end time and removal time, etc. This is fine if the reader is already familiar with the concepts, but hard to understand for the uninitiated.
- The naming in the current documentation is at some points confusing (e.g. it talks about "root" and "top-level" history instances, which is not meant to be the same thing).
- Based on that, it is hard for users to understand how history cleanup works and the pros/cons of the two cleanup strategies.
- Make concepts build on each other. Do not use terms/concepts in a later section that have not been introduced before.
- Use clear naming and try to avoid "artificial concepts"