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.
Never heard about the method before but I've noticed long time ago this is the way that works for me.
When someone starts with definition I get bored. I want to start from example and use case and then I will built a mental formalization on my own. Starting from formalization I just can't be bothered.
You can see the diff e.g. how Wikipedia and Investopedia articles are written.
Each Investopedia article shows an example and repeats some key things multiple times. Whereas trying to learn any economics or maths stuff from Wikipedia is almost impossible. It can only be a reference if you already know the thing and just need to double-check the formula.
This is a disease of Mathematics in general.
Actual mathematics teaching, as seen in typical University classes typically introduces a new abstract definition, and then immediately follows that up with a number of "worked examples", either in the lecture itself or a follow-up tutorial class.
However, the reference material will typically only have the abstract definitions, but at least there will be a sequence of them building up the formalities piece by piece. In principle, a gifted mathematician could follow the trail and get to the "aha!" moment without even having to do the homework problems.
Encyclopedias like Wikipedia or Mathworld tend to just mention the most abstract, "end product" of a long chain of mathematics. Terse formulas by themselves are utterly useless to anyone who hasn't gone through the step-by-step learning process and already understands the topic completely.
It's like a historian being given a handful of Egyptian hieroglyphic characters before finding the Rosetta Stone. It's just squiggles and shapes!
An example I came across personally was the simplification of Maxwell's Equations using Geometric Algebra. In GA, it is possible to write the equations of the EM fields incredibly tersely, down to as little as:
âĄÂ˛A = J
The 5 characters in that equation pack in an awful lot: The Geometric Product. Graded vector spaces. The four dimensional spacetime of special relativity. Vector calculus. Natural physical units. Etc...
Pasting that equation into an article can't possibly cover all of that...
I've also discovered that this type of bottom up approach is faster than the top down approach.
Starting with an example gives a more concrete frame of reference.
I don't think this is just a matter of personal preference either. I believe that the way you learn a new concept is the same way as how you learn to navigate a new physical environment. We don't have a GPS in our brain for mapping, we learn locations by reference to other locations.
This is why I like Jeremy Howardâs approach for teaching machine learning. Begin with simple code and examples, then break apart and explain. https://course.fast.ai/
Same here. I've heard somewhere, in a video about language acquisition, that we have a pattern recognition algorithm in our brains, so all we need is to see examples, and the algorithm does the rest (builds a model by itself).
If curious see also
In my experience the most difficult for us techies to lay down to somebody outside is the analogy. Is the make or break of entire explanation. And usually I fail 75% of the time right there at the start. Some recover later when I go with examples, but most of them are lost from beginning. Yeah, I know, I'd make a terrible teacher.
This is actually really good advice. I've tended to try a formal description of something first, in case the other party knows the jargon, but it's been surprising to me how quickly you can shut someone down by throwing words at them they don't understand.
This website's got some great explanations for topics that a lot of people get hung up on. Here's one of their articles on Flux. [1] I was curious how this mental model compares to other ones I had previously encountered and found this article that compares each. [2]
This is the way that I wish more teachers taught. I love finding analogies or visual diagrams for CS concepts to share with my students.
Request: can others share links to books, courses, videos, articles or other resources that employ incredibly thoughtful pedagogy in explaining, rather than diving into the nitty-gritty details immediately? I'd love to start a collection of examples to share with others.
This is a book on Linear Algebra I am working on: https://moallabbad.github.io/Intuitive-Guide-to-Linear-Algeb...
I am going through somewhat lengthy explanations and using interactive graphs in 2D and 3D. My goal is to introduce things gradually and provide different perspectives to increase the chance of at least one clicking.
Itâs in no way complete. In fact, it currently only has one chapter. But I am actively working on it. Hope you like it.
ADEPT method is like using "Uber for X" to explain an idea. Here, I used ADEPT method to explain the ADEPT method.
Get a daily email with the the top stories from Hacker News. No spam, unsubscribe at any time.