There are so many little gems in this piece by Yevgeniy Brikman all about documentation. He digs into a lot more than simply documenting code though and focuses on how we can document every phase of our work, from design to process and beyond.
Here’s my favorite lines that made me sit back and shout “Wahoo!”:
When a developer uses your code, they are really learning a new language, so choose the words in it wisely.
…programs must be written for people to read, and only incidentally for machines to execute.
I like how Yevgeniy suggests that there are kinda two different mindsets that we have to get into when writing code: one for making the dang thing work in the first place, and another for explaining how and why we did a specific way. There’s context-switching that takes place between those different stages of work.
Anyway, when seen in this light, documentation could be much more than a nice-to-have. Instead, it might just be 50% of the work.