It's important that documentation be clear, discoverable, and up to date. Code-as-documentation is best-in-class at staying up to date, when it comes to docume

It's important that documentation be clear, discoverable, and up to date. Code-as-documentation is best-in-class at staying up to date, when it comes to documenting what a system does and how. Often the relevant pieces are very discoverable as you're going to make a change. For other goals, it's much less discoverable. Clarity depends on both how the software is written and who the audience is. Tests-as-documentation are arguably a special case of code-as-documentation. Outside of the case of well maintained tests-as-documentation, code-as-documentation often has a hard time expressing "why" and distinguishing between what has to be a certain way and what just happened to be that way. It also has some trouble expressing aspiration - "we've decided it should be this way, but it's not yet".