Хороший программист знает, зачем нужен readme-файл.
Но как сделать его понятным другим разработчикам? Ведь если вы выкладываете свой проект на Github, ваша цель – получить оценку профессионального сообщества. Что делать? Рассказываю.
1) Смотрите, как делают другие. На GitHub полно проектов с хорошей документацией. Всегда можно найти что-то для себя:
- Mimesis
- Flask
- Requests
- Python Slugify
2) Пользуйтесь шаблонами. Вот пара примеров:
- A template to make good README.md
- README.md template
3) Добавляйте картинки или видео-описание – сделайте проект наглядным. Только Github не разрешает добавлять видео в readme, лайфхак – используйте gif.
4) Элементы оформления создадут у читающего readme ощущение уникальности вашего проекта. Нестандартные или активно используемые элементы оформления для репозитория можно раздобыть здесь: https://shields.io
5) Если ваш проект не будет выглядеть просто как кусок кода, лежащий на github, это в разы повысит шансы на интерес к вам работодателя и других разработчиков. Что сделать? Разместите проект на своих ресурсах и установите запускаемую демо-версию. В readme можно использовать гиперссылки, так что поместите ссылку на интерактивную демо-версию прямо под изображением с названием.
6) Используйте HTML. Рекомендуется всё же придерживаться разметки, но некоторые функции, такие как выравнивание текста и изображений по центру, в readme доступны только с использованием HTML.
7) Творите! Пусть не только код, но и красивый readme производит неизгладимое впечатление на посетителей вашего профиля на github.
И, удачи!
