From 05e6634ec3ff55bb347123c0681c321b4db8aa9c Mon Sep 17 00:00:00 2001 From: Igor Korovchenko Date: Thu, 21 Sep 2023 16:38:33 +0300 Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB=D1=8F?= =?UTF-8?q?=D0=B5=D1=82=20=D1=80=D0=B5=D1=86=D0=B5=D0=BF=D1=82=20=C2=AB?= =?UTF-8?q?=D0=9A=D0=B0=D0=BA=20=D0=BD=D0=B0=D0=BF=D0=B8=D1=81=D0=B0=D1=82?= =?UTF-8?q?=D1=8C=20README=20=D0=BD=D0=B0=20GitHub=C2=BB=20(#4728)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Добавляет рецепт «Как написать README на GitHub» * Добавляет рецепт в индекс * Принимает правки @TatianaFokina Co-authored-by: Tatiana Fokina * Принимает правки @skorobaeus Co-authored-by: Svetlana Korobtseva --------- Co-authored-by: Tatiana Fokina Co-authored-by: Svetlana Korobtseva --- recipes/github-add-readme/index.md | 50 ++++++++++++++++++++++++++++++ recipes/index.md | 1 + 2 files changed, 51 insertions(+) create mode 100644 recipes/github-add-readme/index.md diff --git a/recipes/github-add-readme/index.md b/recipes/github-add-readme/index.md new file mode 100644 index 0000000000..d542226e5e --- /dev/null +++ b/recipes/github-add-readme/index.md @@ -0,0 +1,50 @@ +--- +title: "Как написать README на GitHub" +description: "Опишите свой продукт на GitHub правильно." +authors: + - igsekor +related: + - tools/version-control + - tools/git-cli + - tools/github-actions +tags: + - article +--- + +## Задача + +Добавить базовое описание репозитория продукта на GitHub. + +## Решение + +Файл _README.md_ в корневой папке репозитория — особенный файл для любого продукта. В нём, как правило, даны самые основные сведения о репозитории: + +- название продукта; +- краткое описание; +- основные возможности; +- инструкция по установке и/или подключению; +- инструкция по запуску в режиме разработчика и в режиме пользователя; +- список участников репозитория, которые разрабатывают и поддерживают продукт. + +Написать хорошее описание продукта непросто, и это требует определённого навыка. Хорошей идеей будет посмотреть, как это делают коллеги. В каждом продукте есть и что-то схожее с остальными, и по-своему уникальное. Важно правильно расставить акценты. Помните, что _README.md_ — обложка вашего проекта. + +Потребителями _README.md_, скорее всего, будут разработчики и продвинутые пользователи, например, администраторы систем. Язык программирования, выбранные задачи репозитория, принятые в сообществе нормы описания будут определять содержимое файла. Хорошее описание поможет продвинуть продукт. Его легче будет найти на GitHub и в поиске, а ещё им будет комфортнее пользоваться. Хорошее описание привлекает хороших разработчиков. + +В _README.md_, в первую очередь, ответьте на следующие вопросы: + +1. **Почему был создан продукт?** В ответе на этот вопрос можно опираться на такие понятия как мотивация, история, потребности, мечты и прочее. +1. **Для чего был создан продукт?** Здесь лучше всего описать те проблемы и потребности, которые закрывает продукт. +1. **Чем продукт лучше аналогов?** Если у продукта есть аналоги, необходимо написать об отличиях и особенностях продукта. +1. **Как установить продукт?** Тут необходимо написать краткую инструкцию по установке. +1. **Как пользоваться продуктом?** Тут нужно написать краткую инструкцию пользователя из серии «Быстрый запуск». +1. **Как помочь продукту развиваться?** Здесь лучше ответить тем разработчикам, которые хотят поучаствовать в развитии продукта. +1. **Кто разрабатывает продукт?** Самый простой ответ на этот вопрос — список разработчиков, но может быть и описание компании или инициативы, в рамках которой продукт был создан или развивается. + +В _README.md_ используется разметка в [формате Markdown](/tools/markdown/). Структурируйте текст файла, выделяя каждый блок заголовками и подзаголовками. В интерфейсе GitHub заголовки хорошо выделяются на фоне текста до третьего уровня, поэтому старайтесь использовать заголовки первого и второго уровня. Возможная структура _README.md_: + +- **название** (заголовок первого уровня) — название продукта без указания версии, если в этом нет особенной необходимости, например, из-за лицензии; +- **описание** (заголовок второго уровня) — краткое описание продукта, в котором можно ответить на вопросы 1, 2 и 3 из списка вопросов выше; +- **установка** (заголовок второго уровня) — описание процесса установки продукта (вопрос 4); +- **использование** (заголовок второго уровня) — описание процесса использования продукта (вопрос 5); +- **разработка** (заголовок второго уровня) — описание процесса того, как принять участие в разработке проекта или запрет на это (вопрос 6); +- **участники** (заголовок второго уровня) — перечисление всех, кто принимал или принимает участие в разработке продукта (вопрос 7). diff --git a/recipes/index.md b/recipes/index.md index 7082ef8a4d..7382013c93 100644 --- a/recipes/index.md +++ b/recipes/index.md @@ -23,6 +23,7 @@ groups: - github-choose-license - github-add-user-to-repo - github-new-pull-request + - github-add-readme - name: 'Рутина' items: - font-script