I was reading a mailing list I’m subscribed to and I saw the following
The people already doing this probably consider this trivial, so it’s not well documented.
This statement is both very true, and very awful. There are lots of things that people who know only a little find terrifyingly complicated – too complicated to even approach – and those who know a lot about it find totally trivial – too trivial to even write down.
Two questions emerge: what are these things, and how can we document them. In reverse order, I think that wikis and other collaborative lowest-common-denominator-type systems can help a whole lot. People often complain that wikis are disorganized, but I’ll take disorganized over nonexistent every day.
As to what is this trivial stuff, things in this category include “recompiling and installing your own kernel”, “how CGI scripts work”, “how to search logs”, and “how gui software works”. Actually, lots and lots of software practices are exactly like this. The people who know too much never write it down, which means that the same lessons keep getting relearned by each successive generation, and that progress never gets made, because the things that are needed to know to make the progress are too trivial.
So here’s my new theory: nothing is trivial.
Shell scripts are not trivial. HTML is not trivial. Email is not trivial. CGI is not trivial. Coding a basic GUI app is not trivial. Compiling is not trivial. Your IDE is not trivial. That interface is not trivial.
Nothing is so easy that it doesn’t need to be documented. EveryTHING doesn’t need to be documented everyWHERE, but everything should be documented somewhere. And that documentation needs to evolve with the times. As communities of users become more sophisticated, they need both explanations of the new stuff, as well as clearer and cleaner and simpler explanations of the old stuff.
Writing python code is pretty trivial to me now. Sometimes the tasks are not, but once I understand the task, the code comes naturally. This probably means that a) I should get out of my rut and learn a few new languages and b) I should leverage my knowledge to help the next generation of coders to more quickly become as proficient as I am. It’s similar to Buckminster Fuller’s idea that world shortages of machined goods could be fixed by giving someone a lathe and mill and teaching them how to use them on the condition that they make 2 mills and 2 lathes and give them away to others and teach those others how to use them. A pyramid scheme of skill, if you will. Just don’t refer to it as “paying it forward”.
