[benrutter]

I've seen it done really well, really badly, and not at all!

Here's some things that I think help

- Tie documentation to code wherever possible: Automated API documentation is an obvious example, but even moves like including a 'developer guide' in the repo rather than a seperate file somewhere is a significant improvement.

- Manually written documentation will drift: This means you need capacity to maintain it. You're much better off manually documenting a few high level design choices and keeping it up to date, than trying to capture everything and it becoming inaccurate.

- Developer experience reduces the need for documentation: If you can automate stuff as much as possible, including offloading things to a type system etc to rule out mistakes, you'll reduce the amount new developers need to know to be effective, and therefore the ammount that has to be extensively documented. People are better learners when they do it slowly as they need than when they get given everything in one huge document to read.