I've been a full-time technical writer for ~8 years. These seem like solid guidelines to me.
One trick-of-the-trade that I've learned about diagrams is to avoid hardcoding English text into the diagram if you're working on an internationalized doc site. Instead, insert numbers like "(1)" and "(2)" and then provide a numbered list after the diagram explaining each number from the diagram. This makes the content easier to translate. E.g. if you hardcode English into the diagrams, you've got to translate that diagram for every language or (more realistically) your non-English docs are going to have English text hardcoded into their diagrams. Hat tip to David Friedman for teaching me that trick.
I've sometimes had technical people take issue with analogies precisely because they're not completely technically accurate. When that happens I compromise with them by adding an explicit sentence right before or after the analogy along the lines of "This is just an analogy to help you develop an intuition for the topic. It's not 100% technically correct. See X for technical details."
I think the importance and helpfulness of examples is majorly underrated across docs sites.
It may hark back to the terse crypticness of Unix manpages.
On the other hand, php has a better balance with user contributed examples at the end of the official doc, with exceptional comments and examples eventually becoming part of the official documentation.
One trick-of-the-trade that I've learned about diagrams is to avoid hardcoding English text into the diagram if you're working on an internationalized doc site. Instead, insert numbers like "(1)" and "(2)" and then provide a numbered list after the diagram explaining each number from the diagram. This makes the content easier to translate. E.g. if you hardcode English into the diagrams, you've got to translate that diagram for every language or (more realistically) your non-English docs are going to have English text hardcoded into their diagrams. Hat tip to David Friedman for teaching me that trick.
I've sometimes had technical people take issue with analogies precisely because they're not completely technically accurate. When that happens I compromise with them by adding an explicit sentence right before or after the analogy along the lines of "This is just an analogy to help you develop an intuition for the topic. It's not 100% technically correct. See X for technical details."
I think the importance and helpfulness of examples is majorly underrated across docs sites.