I totally agree with you. It requires good understanding of the project but also it's beneficial to know the pitfalls and decisions made or left unmade that ended up shaping the project. That's why I encourage developers to make documenting (just like testing) a part of feature development and bug fixing rather than an additional hurdle.

I like Tom Preston-Werner's Readme Driven Development[0] approach. Instead of leaving documentation as something that happens as an afterthought, start with it. I've tried it a few times with my smaller hobby projects and it has helped me a lot.

Similar to TDD, RDD allows me to design the API before I ever write the actual code. I also get to design the build process, contribution model and bunch of other things up front.

When it comes to the "why" of projects, I like DHH's Doctrine document[1] on Ruby on Rails. I wish more software projects would feature a similar document since that answers a lot of questions, especially about the opinionated decisions.

[0] http://tom.preston-werner.com/2010/08/23/readme-driven-devel... [1] https://rubyonrails.org/doctrine/