Open Source
README и документация
Axios имеет 100+ млн downloads в неделю. Значительная часть успеха - простой README с понятным примером кода в первых строках. Разработчик видит 3 строки кода и понимает «это то что мне нужно». Документация продаёт библиотеку.
- Zod README начинается с 10 строк кода - без многословных объяснений
- Prisma документация - пример как docs могут быть конкурентным преимуществом
- lodash потерял долю рынка когда появился better-documented native alternatives
- TanStack Query (бывш. React Query) - документация считается лучшей в экосистеме
Структура хорошего README
README - первое что видит потенциальный пользователь вашего пакета. У него есть 30 секунд чтобы решить: стоит ли разбираться дальше? Хороший README отвечает на три вопроса: **что это**, **зачем нужно**, **как начать**.
**Badges - не украшение.** npm version badge обновляется автоматически и показывает актуальную версию. CI badge показывает что код работает. License badge устраняет правовую неопределённость. Вместе они создают сигналы доверия за 2 секунды.
**Избегайте этих ошибок в README:** 1) Нет примера кода - только описание. 2) Пример показывает hello world без реального use case. 3) API section устаревший (хуже чем отсутствующий). 4) Installation только через npm, без yarn/pnpm. 5) Нет «Why» section - почему не использовать конкурентов?
Пользователь смотрит на ваш README. Что НАИБОЛЕЕ важно для решения «установить или нет»?
JSDoc, TSDoc и генерация документации
Хорошая документация - это не только README. Для библиотек важна **API-документация прямо в коде**: JSDoc/TSDoc комментарии которые IDE показывает при hover и которые можно автоматически опубликовать.
Зачем использовать @example в TSDoc комментариях к функциям библиотеки?
Ключевые идеи
- README структура: badges → tagline → Why → Install → Quick Start → API → Contributing
- Why section устраняет главный вопрос: почему не использовать X вместо этого
- TSDoc @example - IDE показывает при hover, typedoc включает в docs, некоторые инструменты тестируют
- typedoc + GitHub Pages = бесплатная хостинг документации
- Устаревшая документация хуже отсутствующей - поддерживайте актуальность
Связанные темы
Документация готова. Следующий важный шаг - версионирование и CHANGELOG.
- Следующий урок курса — Логическое продолжение
Вопросы для размышления
- Найдите README который вы считаете образцовым. Что именно в нём хорошо? Чего не хватает?
- Почему важно иметь @example с реальным use case, а не абстрактным hello world?