News for hackers. Stuff that matters.
Re:The Grand Unified Theory of Documentation by johnchristopher on Friday April 16, 2021 @03:38AM (#26830763)
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.

Re:The Grand Unified Theory of Documentation by unwind on Friday April 16, 2021 @05:50AM (#26831790)
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.

Re:The Grand Unified Theory of Documentation by samus on Friday April 16, 2021 @08:15AM (#26832925)
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.

Re:The Grand Unified Theory of Documentation by toomanybeersies on Friday April 16, 2021 @09:42AM (#26833747)
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

Re:The Grand Unified Theory of Documentation by JimDabell on Friday April 16, 2021 @03:49AM (#26830840)
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 [..].