Как сделать документацию полезной

Польза документации по проекту не в только том, чтобы она описывала «что это за хрень», а ещё и «почему эта хрень сделана вот так».

Описывайте причины, по которым приложение работает именно так, как работает. Рассказывайте о проблемах, с которыми столкнулись при разработке, и ходе решения этих проблем.

В идеале новичок, прочитав доки, должен узнать обо всех компромиссах и спорных решениях в проекте. Потому что без них теряется огромная часть контекста, и, скорее всего, новые разработчики будут повторять старые ошибки.