We're updating the issue view to help you get more done. 

Don't use confusing "this" in the User Guide admonition blocks

Description

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.

Environment

None

Status

Assignee

Vlad Mihalcea

Reporter

林自均

Fix versions

Labels

None

backPortable

None

Suitable for new contributors

None

Requires Release Note

None

Pull Request

None

backportDecision

None

Components

Priority

Minor