Open
Description
A perennial cause of confusion in Hypothesis is how document metadata is managed and used. This includes topics such as:
- What is URI normalization, how does it work and what are the consequences?
- What document URIs are captured by the client and stored in h
- What document metadata is captured by the client and stored in h
- What affects the annotations that are fetched when annotating a particular document
- What changes to a document will "break" the link between annotations and its document
- How can incorrect document metadata be corrected
- How can document metadata be updated if URLs are moved to a new location
Audiences for this documentation, or parts of it, include:
- Hypothesis developers, especially new ones trying learning about the system
- Customer support staff who need to understand at least parts of this to assist users
- End users who are trying to understand how Hypothesis associates annotations with URIs
Since these audiences will be interested in understanding this at different technical levels, it might make sense to write up documentation in the docs/ dir in the h repo which contains a technically detailed version maintained by H engineers. The support team can then distill that down to information that is easier for end-users to understand as necessary.