[johnchristopher]

It may be due the language barrier or something but there are some phrasing that really throws me of:

> You might send variables to this server function by calling this endpoint from your javascript code.

You might but in fact you must (or you can) because it is the only way send variables to the server from Javascript. It's not like it's a personal preference or that there is another way.

> You can choose to use `register_rest_route()` to register a custom route [..].

But this is the only way to register a route.

[unwind]

I couldn't figure out what you are quoting, but to me "sending a variable" signals major confusion with the author, in the general case.

Values (being data) can be transmitted, actual variables (being programming-language constructs to contain values and make them available to operate upon) cannot.

[samus]

The wording "might" really triggers me because it stands for something that /could/ happen. It is one of the ways to express the conjunctive mood (possibilities, wishes, ambiguity), which has absolutely no right to exist in a technical documentation.

~~There is only one place where this makes sense: in a best-practices section explaining consequences. But also there I want to see clear facts instead of unclear statements making me chase ghosts.~~

Edit: No, just plain facts please.

[toomanybeersies]

This is where RFCs get it right (although technically they're standards, not documentation), with standardised language [1]

e.g.

> MUST: This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.

[1] https://tools.ietf.org/html/rfc2119

[JimDabell]

As with most things, you can improve the writing by removing unnecessary words:

> You might send variables to this server function by calling this endpoint from your javascript code.

…becomes:

> send variables to this server function by calling this endpoint

…and:

> You can choose to use `register_rest_route()` to register a custom route [..].

…becomes:

> Use `register_rest_route()` to register a custom route [..].