31–40 of 58 posts
In case you went "hey, this looks like a blatant rip-off of Divio's pages, doesn't it?" -- yeah it is, because this is the spin-off of that particular aspect from Divio.
Earlier quoted context omitted.
Agree to all! When I was rewriting the OneSignal docs I followed the same rules you laid out as well as a few more: 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…
About 8: this habit might make your docs sound a bit monotonous, but it also helps with 'grepping' through them.
Some personal rules for docs: 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 ter…
> 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.
Documentation fulfills five important functions:
- Communications to management about the progress of
the project, providing intermediate product
visibility
- Task-to-task communication
- Instruction and reference
- Quality assurance support
- Historical reference
Some personal rules for docs: 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 ter…
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 `re…
> 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 [..].
It now has its own domain, because it's about time. This is where it will continue to be updated and maintained.
A quick clarification: I am still at Divio, but after a break in June I'll be looking for something new.
If you have a notable product, a large developer user-base, a positive internal culture, and need to address some significant challenges in developer education/documentation, at the highest level - get in touch: daniele@vurt.org
I should also like to point out that when I posted this a week or so ago, it got just three points https://news.ycombinator.com/item?id=26724825. Very unfair.
Hi everyone. I'm Daniele, author of the framework. It now has its own domain, because it's about time. This is where it will continue to be updated and maintained. A quick clarification: I am still at Divio, but after a break in June I'll be looking for something new. If you have a notable product, a large developer user-base, a positive internal culture, and need to address some significant challenges in developer e…
Best of luck with the job hunt..!
In case you went "hey, this looks like a blatant rip-off of Divio's pages, doesn't it?" -- yeah it is, because this is the spin-off of that particular aspect from Divio.
can you provide a reference link so that some of us can understand Divio? Thanks!