Examples Are the Best Documentation
Разработчики часто сталкиваются с тем, что официальная документация описывает функцию, но не показывает, как её использовать. Пример: вместо того, чтобы показать, как вызывать max() в Python, документация тратит абзацы на то, чтобы объяснить, что такое iterable и что значит key=. А ведь достаточно было бы показать, как передавать кастомную функцию сортировки в max().
Проект ClojureDocs берёт на себя роль «примеры — лучшая документация». Пользователи добавляют примеры к встроенным функциям, и это оказывается куда более полезным, чем формальное описание API. Примеры показывают, как вызывать функцию, какие есть подводные камни и какие есть альтернативы.