Yeah the documentation (if it even exists) of most projects is usually clearly written by people intimately familiar with the project and then never reviewed to make sure it makes sense for people unfamiliar with it. But writing good detailed documentation is also really hard, especially for a specialist because many nontrivial things are trivial to them and they believe what they’re writing is thorough and well explained even though it actually isn’t.

I write technical documentation and training materials as part of my job, and the state of most open source documentation makes me want to stab people with an ice pick.

This reminds me of when I sent someone a program in a zip folder. Windows now opens zip folders by default, and it looks just like any other folder.

So of course they opened the zip and double clicked the exe, but everyone knows you can’t open an exe inside a zip folder (at least, if the exe depends on the folders and files around it). If you try to, windows will extract the exe into a temp space, but leave all the dependencies behind. So the exe promptly crashes.

I didn’t think I needed to specify “you need to extract the contents of the zip folder first, then run the exe.” It feels like saying “you need to take the blender out of the box before you can use it. And not just the _base _ of the blender, you have to take out all the parts.”

Some things just feel so much like second nature that we forget.