Источник: Nuances of Programming
Readme — это детальное описание проекта. В нем содержится информация о том, что представляет собой проект, кто его авторы, как он устанавливается или настраивается, как используется и прочие данные.
Readme — визитная карточка проекта. Всякий раз, когда кто-то заходит в репозиторий, он первым делом просматривает readme-файлы, чтобы получить представление о проектах. Детальный readme создает хорошее первое впечатление о проекте.
Хотите узнать, как создать впечатляющий детальный readme-файл для любого проекта? Тогда без лишних слов перейдем непосредственно к делу.
Зачем нужно писать readme?
Readme помогает людям понять, о чем ваш проект. Это обязательное условие для разработки проекта с открытым исходным кодом. Но даже если вы создаете закрытую систему, следует написать readme, чтобы коллеги по проекту могли вникнуть в его суть. Кроме того, написание отличных readme помогает найти хорошую работу.
Особенности
Readme-файлы обычно пишутся на языке Markdown. Поговорим об основных особенностях его синтаксиса — это знания пригодятся не только для readme, но и для любого другого документа.
Примеры использования синтаксиса Markdown.
1. Начнем с того, что Markdown поддерживает языки разметки. Поэтому, если вы знакомы с HTML, можете использовать его синтаксис.
2. Перед заголовком ставится обозначение хештега #. Количество хештегов соответствует уровню заголовка. В Markdown используются заголовки 6 уровней.
Например:
# Это заголовок 1-го уровня
## Это заголовок 2-го уровня
### Это заголовок 3-го уровня
3. Добавление дополнительного разрыва строки в абзаце разделяет абзац. Например:
Это первый абзац.
Это второй абзац.
4. Выделение части текста жирным шрифтом достигается с помощью**. Например, код **текст** приведет к записи текст.
5. Для выделения части текста курсивом используется один символ *. Например, код *текст* приведет к записи текст.
6. Упорядоченный список оформляется следующим образом:
1. Это элемент 1 упорядоченного списка.
2. Это элемент 2 упорядоченного списка.
3. Это элемент 3 упорядоченного списка.
Вы также можете создать неупорядоченный список:
- Это элемент 1 неупорядоченного списка.
- Это элемент 2 неупорядоченного списка.
- Это элемент 3 неупорядоченного списка.
7. Изображения в readme добавляются с использованием следующего кода:
8. Ссылки можно добавить, используя приведенный ниже код:
[Текст ссылки](https://путь/к/ссылке)
9. Чтобы показать примеры кода в readme, используйте следующие символы:
`Это встроенный код
````
Это блок кода
```
Это практически все, что вам нужно знать для написания readme, дополнений к коду или любых других документов в формате Markdown.
Теперь, познакомившись с основными синтаксическими особенностями Markdown, углубимся в процесс создания readme.
Пошаговый процесс написания readme
К счастью, вам не придется создавать этот файл с нуля. На GitHub представлено множество образцов, которые помогут легко создать свой.
Awesome readme — отличный ресурс для поиска конструкций, подходящих для конкретных проектов.
Например, шаблон Best-Readme-Template обладает многими функциональными возможностями, полезными для демонстрации проектов. Итак, создадим readme с его помощью.
Шаг 1. Создание репозитория GitHub
Сначала создадим репозиторий GitHub, нажав на кнопку с плюсом в правом верхнем углу. Дайте проекту title (название), description (описание) и отметьте Add a README file (Добавить файл README). После этого нажмите на кнопку Create Repository (Создать репозиторий).
Шаг 2. Копирование Readme-контента в readme репозитория
Перейдите в репозиторий Best-Readme-Template и кликните файл README.md. Затем нажмите на кнопку Raw.
После этого скопируйте все тексты, отображаемые в браузере. Затем вставьте их в файл readme.
Для этого нажмите Edit (Редактировать) в файле README.md:
Шаг 3. Изменение файла README в соответствии с деталями проекта
Теперь пришло время изменить файл README.md в соответствии с содержанием конкретного проекта. Начнем с изменения названия и описания.
Точно так же измените остальные разделы в соответствии со спецификой проекта. Если потребуется, можете добавить или удалить какие-то разделы.
Обратите также внимание на ссылки и изображения — измените их соответствующим образом.
Чтобы увидеть внесенные изменения, нажмите кнопку Preview (Предварительный просмотр).
Еще одна вещь, на которую стоит обратить внимание, — это возможность добавить настраиваемые шилды. Они могут представлять состояния репозиториев или ссылаться на профиль LinkedIn.
В шаблонах readme можно найти некоторые шилды, как показано ниже:
Прокрутив страницу вниз, можно настроить шилды в соответствии с проектом:
Как указано на изображении выше, нужно изменить имя пользователя GitHub и URL репозитория соответственно всем ссылкам. После этого увидите “магию” преображения в процессе предварительного просмотра.
Здесь можно просмотреть другие шилды.
Шаг 4. Сохранение и фиксирование изменений
После внесения изменений в файл readme прокрутите страницу вниз до раздела Commit changes, напишите сообщение о фиксировании изменений и нажмите на кнопку Commit changes (Зафиксировать изменения).
Readme-файл готов!
Заключение
Теперь вы знаете, как создать в репозитории впечатляющий, детализированный и хорошо организованный файл Readme.
Такие readme создают наилучшее впечатление о разработчике. Они доказывают, что проект организован, документирован и обеспечен надежной поддержкой.
Читайте также:
Перевод статьи Rashedul Alam: How to Write a Stunning Readme for Your Projects