[GinsengJar]

Great read, solid principles.

It took me too long realize I'd be saving time by spending more time adding meta sections to my documentation. "Devs will understand," I said, and boy was I sippin on my own juice.

[washadjeffmad]

I get flack for being descriptive, citing prior policy, and putting things on timelines when everyone is in the know, but the second they move on to the next crisis or a re-org happens and no one knows how the fuck anything is working, guess who they come to?

Nobody. Asking for help would imply they don't know what's going on, which would be embarrassing, so they rebuild from scratch for the dozenth time, duplicating all the same mistakes, just in $HotNewThing.

The auditors like me, at least.

[kaycebasques]

Here's a quote from a book called Living Documentation that I think will resonate a lot with you. Long but worth it:

> Software development is all about knowledge and decision-making based on that knowledge, which in turn creates additional knowledge. The given problem, the decision that was made, the reason it was made that way, the facts that led to that decision, and the considered alternatives are all knowledge... each instruction typed in a programming language is a decision... Software design can last a long time. It can last long enough to forget about previous decisions made, as well as their contexts. It can last long enough for people to leave, taking with them their knowledge, and for new people to join, lacking knowledge. Knowledge is central to a design activity like software development. Most of the time this design activity is, for many good reasons, a team effort involving more than one person. Working together means making decisions together or making decisions based on someone else's knowledge. Something unique with software development is that the design involves not only people but also machines... Using a formal language like a programming language, we pass knowledge and decisions to a computer in a form it can understand. Having a computer understand source code is not the hard part... The hardest part is for other people to understand what has been done so that they can then do better and faster work. The greater the ambition, the more documentation becomes necessary to enable a cumulative process of knowledge management that scales beyond what fits in our heads. When our brains and memories are not enough, we need assistance from technologies such as writing, printing, and software to help remember and organize larger sets of knowledge.

Highly recommend reading the first chapter of the book. I'm not sold on the proposed solutions covered in the rest of the chapters.