The info box will sometimes refer some object with "this". Readers usually need to read lots of the context to understand what "this" means. Sometimes, I can't even understand what "this" means after reading the context paragraphs.
For example, in "15.4. Hibernate Query API", there is an info box says:
> This form should be considered deprecated and may be removed in the near future.
However, there are a lot of forms of parameter binding above. The nearest example uses "?1", but the nearest paragraph mentions "?" without a following ordinal. So which one is deprecated?
Another example is in "15.8. Update statements". There is an info box says:
> This is a Hibernate specific feature and will not work in a portable manner.
I am not sure whether the whole update statements is Hibernate specific or just the "VERSIONED" keyword. If it's the "VERSIONED" keyword is Hibernate specific, it's nicer to see an info box just says "The VERSIONED keyword is Hibernate specific."
Since I am not an English native speaker, I am not sure whether other people have similar problems. But it bothers me a lot when reading the user guide. Hope you can improve it, or give me some guidance for improving it.