The [[Agile]] movement has taken the business and software world by storm. One of its 4 big value statements says: > [!quote] Working software over comprehensive documentation This means that there's explicit tension between creating & maintaining documentation and "being agile". This is one argument for [[Code Auto-Documentation]], although even _that_ is arguably too much documentation for some code. [[Great Code Doesn’t Need Comments]]. But, no matter how readable the code is, it won't be as effective at describing the big picture as a simple diagram, which is partly why [[Diagrams as Code]] is a thing. Even then, you may want to capture [[Architecture Decision Records]] in a repository alongside your code. Certain architectural choices will need made that will lead to inevitable [[Tradespace|trade offs]] - an ADR explains the _rationale_ behind a decision **quickly**, so it can be decided later on if that rationale still stands. **** # More ## Source ## Related