5. Get every step right. Don't make assumptions that the reader knows how to configure something you mention in passing, spell it out. This is especially important if good engineers are writing docs since they leap over little things that less skilled users might not know.
6. Write for translators. Many users don't speak English well and will be running docs through Google Translate. This is a variant of your #1.
7. Consider docs a seamless extension of the product. Use the exact wording and same visual language of the product and make sure docs pick up from where exactly the user was in the product. Evaluate these flows so wherever someone gets tripped up, the right doc is there waiting. Ideally do bidirectional linking so the product itself also links to these.
8. Super consistent language. Figure out your nouns and verbs: someone playing a game is always a 'player' (vs sometimes a 'user' or 'gamer'), someone sending a file is always 'transferring' (vs sometimes 'sending' or 'uploading'), etc. Unless you pay close attention ambiguity is going to creep into documentation.
As someone with English as a second language seeing "foobar" all over the place in lot's of different contexts really confused me a lot early on. Especially when docs started talking about a "foo" and a "bar".
I still don't understand why it is the generic go to word for examples, it makes little sense.
If real examples from a blog or accounting software had been used instead then I would likely have understood it a lot easier.
In economics textbooks, companies always produce 'widgets'. https://en.wikipedia.org/wiki/Widget_(economics)
Remind me why I'm here in this document, because I might be in the wrong place.
But in terms of a process. Eg how are you going to keep the docs up to date?
> 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.
Values (being data) can be transmitted, actual variables (being programming-language constructs to contain values and make them available to operate upon) cannot.
~~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.
e.g.
> MUST: This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.
> 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 [..].
1. Explain, in plain non-jargon words (nobody cares how smart you are) what problem is being solved, how, and why.
2. Provide contextualized examples (no foobar), not making assumptions about what the reader knows or doesn't know (and avoiding condescending language like "it's easy," "it's common sense" or anything that suggests the reader is "dumb" if they don't get it).
3. Think in terms of a blog post/tutorial, not technical API docs as a starting point. This helps with adoption because people want to understand the thing first and then dig into API (just because you may not doesn't mean that others are the same).
4. Don't be lazy. Show respect for the people taking the time to use your stuff and put in the effort (grammar, structure, quality of examples, etc).