The "why" is the most underrated aspect to good documentation. I generally prefer the word "context". The trickiest aspects of writing and editing software te

The "why" is the most underrated aspect to good documentation. I generally prefer the word "context". The trickiest aspects of writing and editing software tend to boil down to two subjects: 1. What's the underlying system we are trying to manipulate? How is its data structured, and what kind of loops and logic branches can be hijacked for our new functionality? 2. Where and when is our new code interacting with the underlying structure? 3. To tie the first two together, what data/functionality are we exposing to the user? How and when? What is the user? Most contemporary programming over the last two decades has been focused on nouns. The last 5-10 years has seen a shift in popularity to verb-based (functional programming) paradigms. We can find insight from noun-based programming to answer "what?", and verb-based programming is good at answering, "how?". Neither really do a good job of answering "where?" or "why?". Those have to be peiced together like evidence in a crime scene, and by the time you figure it out, you've probably learned everything there is to know about the entire codebase.