​​Что делать, чтобы документацию читали?
Принести документацию ближе к пользователю. Прямо туда, где он столкнётся с проблемой и будет нуждаться в документации.

Хороший пример: доки по синтаксису языка Elm принесли в сообщения об ошибках в синтаксисе. Теперь эти сообщения помогают изучить синтаксис и исправить ошибку.