The Awesome Power of Well-Documented Code

Back when I was researching <a href="https://www.penguinrandomhouse.com/books/539883/coders-by-clive-thompson/" rel="noopener ugc nofollow" target="_blank">my book Coders</a>, I talked to a lot of folks who ran very successful open-source projects. “What”, I asked them all, “made your project take off?” Why did yours gain legs, when so many others — including quite good projects — languished, and never attracted much interest? Most of them all said something that warmed my little programmer-and-liberal-arts-nerd soul: <blockquote> “We had really good documentation.” </blockquote> “Documentation” — for those who aren’t already hipdeep in the swamps of software development — means what it sounds like. It’s when the coders sit down to write careful instructions on how, precisely, someone else can use their open-source code. Often they’re writing these instructions for other coders. For example, a few months ago I tried using <a href="https://kaboomjs.com/" rel="noopener ugc nofollow" target="_blank">the Kaboom javascript software that helps you write little video games</a>, so I used <a href="https://kaboomjs.com/doc/intro" rel="noopener ugc nofollow" target="_blank">their documentation and tutorials</a>. Documentation is all about being an excellent writer. Specifically, it requires us to do something quite challenging: To imagine ourselves in the shoes of someone who’s never used our code … so we can carefully guide them through. We have to develop a strong theory of mind for the newbie. We have to dispense with as much jargon as possible, and intuit the things about our code that might seem awkward or baffling at first. Many software developers are terrible at this. To be fair, most everyone is bad at it; hell, I know full-time journalists who fail at this task all the time. The writing of documentation is, in other words, a liberal art. <a href="https://betterprogramming.pub/the-awesome-power-of-well-documented-code-cadf42e07be3">Read More</a>