В очередной раз Алексей нарыл отличную заметку про документацию — Examples are the best documentation. Ключевая мысль:
Кажется, что по умолчанию формальная техническая документация ориентирована на тех, кто глубоко погружён в экосистему. Но многим разработчикам приходится ежедневно держать в голове множество «миров». При переключении между проектами, языками и фреймворками требуется немало умственных усилий, чтобы восстановить контекст и понять, что происходит.
С этим сложно не согласиться. И из этого следует, что один короткий и емкий пример использования дает ответы на большинство вопросов разработчика. К сожалению, в большинстве случаев примеры запутанные, и авторы хотят показать «все-все» фичи. Хотя мой опыт подсказывает, что лучше всего работает пачка лаконичных простых примеров использования.