Зачем нужен README
Что делаем: открываем README.md компонента и описываем, для чего нужна кнопка и когда её брать не стоит.
Для кого пишем
У документации три читателя: разработчик, который подключает компонент; другой верстальщик, который будет править его через полгода; и вы сами через месяц, когда забудете, почему всё так устроено. Всем нужны ответы на вопросы «что это», «когда брать» и «когда не брать». Код отвечает на вопрос «как», но не на «зачем».
С чего начинается README
Название, одна фраза о назначении и два списка:
- «Когда использовать» — ситуации, ради которых компонент создан;
- «Когда не использовать» — самый ценный раздел: он останавливает ошибку до того, как она попала в код.
В примере в разделе «Когда не использовать» стоят две частые ошибки. Кнопкой оформляют переход на другую страницу, хотя для этого есть ссылка <a>. И кнопкой изображают переключатель, хотя для него нужен <input type="checkbox">.
Пишите коротко. README открывают, чтобы за полминуты решить, подходит ли компонент. Подробности лежат ниже и в других файлах.
Источники
- Элемент button: что кнопка обязана делать по стандарту.
- Элемент a: ссылка ведёт на ресурс, действие запускает кнопка.
- CommonMark: синтаксис Markdown, на котором написан README.