The following text is a partial translation of the original English article, performed by ChatGPT (gpt-3.5-turbo) and this Jekyll plugin:
Некоторое время назад я написал блог-пост Открытый исходный код еще не является открытым проектом с открытым исходным кодом, в котором предложил несколько важных качеств хорошего репозитория/проекта с открытым исходным кодом. Одним из них был хорошо написанный файл README. Здесь я попытаюсь дать несколько подсказок о том, как создать хороший файл README и какие ошибки избегать. Надеюсь, это будет полезно для вас.
Я перечислю все, что вам нужно иметь в файле README, в порядке, в котором эти элементы должны появляться:
Зачем их включать? Название уже содержится в URL вашего репозитория, а описание проекта находится в подзаголовке GitHub. Зачем повторяться? Вместо этого начните с логотипа, а сразу за ним добавьте список значков.
Обратите внимание на пустую строку после логотипа. Не забудьте указать размер изображения в атрибуте height. Вы можете пропустить width, так как одного измерения достаточно для HTML. Не делайте его выше 100px в высоту.
Вам нужны эти значки, как я уже говорил ранее. Но вопрос в том, как их разместить внутри README. Вы должны помещать не более пяти значков в одну строку. Затем отделяйте строки пустой строкой. Посмотрите, как это сделано в нашем репозитории zold-io/zold.
Вы должны как-то группировать их в строках, используя какую-то логику. Я группирую их по уровню технических деталей. Первая строка относится к CI, покрытию кода, качеству кода. Вторая строка больше оправдана управлением и т.д. Это на ваше усмотрение, но убедитесь, что все значки, которые находятся в одной строке, имеют одинаковую высоту! Если у какого-то значка высота отличается от остальных, выделите для него отдельную строку, но никогда не помещайте два значка разной высоты в одну строку!
Также помните, что только в нескольких очень специфических случаях (например, значки) вы можете допустить строки длиннее 80 символов. Относитесь к вашему README-документу как к исходному коду. Оформите его правильно и элегантно. Ширина строки - одно из правил форматирования, которые сделают ваш документ более привлекательным. Восемьдесят символов. Вот и все.
Ваш первый абзац после значков должен объяснить, о чем продукт. Обратите внимание: абзац, а не страница текста. Вы должны поместить описание продукта в один единственный абзац. Никаких маркеров здесь, никаких новых строк, никаких отступов. Просто простой текст:
Обратите внимание, здесь пока нет заголовков. Только логотип, несколько строк с значками и простой текст с описанием продукта. Здесь вы можете и должны использовать markdown и указывать читателю на любые соответствующие блоги или видео на YouTube или что-либо еще, но убедитесь, что вы поместите всю свою идею в один параграф.
Затем, снова без заголовков, вы сразу переходите к сути того, как я могу использовать вашу программу, будучи полным новичком в этом репозитории. Я только что открыл эту страницу, потому что мой друг сказал мне, что она замечательная, и я хочу понять, стоит ли она того или мне следует закрыть ее прямо сейчас. У меня есть еще 60 секунд вашего внимания. Расскажите мне, как ее попробовать! Что-то вроде этого:
Затем вы запускаете его и следуете инструкциям:
Должно быть ясно, что делать. Если нет, задайте нам вопрос в нашем Telegram-чате. ```
Обратите внимание на форматирование. Я не делаю отступы и использую тройные апострофы для форматирования примеров кода. Вам следует делать то же самое. Разделяйте текстовые блоки одной пустой строкой.
Здесь начинается основная часть вашего README. Точное содержание зависит от вашего конкретного делового случая и характера вашего продукта. Однако, независимо от продукта, есть несколько рекомендаций.
Во-первых, не заменяйте автоматически сгенерированные Javadocs (или что у вас есть на вашем языке) README. README не является документацией для пользователей по всему, что есть в вашем репозитории. Есть другие места для этого. Здесь вы можете объяснить несколько наиболее интересных случаев использования. Посмотрите, как мы это сделали в проекте yegor256/takes.
Во-вторых, начните каждый случай использования с заголовка второго уровня (## в Markdown) и по возможности избегайте заголовков третьего уровня (###). Нужно ли говорить, что четвертый уровень абсолютно запрещен? И, конечно же, снова, не делайте отступы. Всегда начинайте строки текста с крайнего левого положения, независимо от того, является ли это абзацом текста или заголовком раздела.
В-третьих, имейте в виду, что вы очень скоро измените свой продукт и не хотите всегда помнить, где в файле README вам нужно что-то изменить. Вы хотите, чтобы ваш README был как можно кратким и высокоуровневым. Поэтому, если вы можете, избегайте конкретных деталей и вместо этого направьте читателя на соответствующие части автоматически сгенерированной документации.
В-четвертых, используйте как можно меньше слов. Никого не интересует читать вашу прозу более нескольких секунд и только для того, чтобы понять, как использовать ваш продукт или как внести некоторые изменения. Не фокусируйтесь на себе, нам нет дела до вас. Сосредоточьтесь на нас и наших потребностях. Расскажите нам, как это работает, и называйте это README. Без философии, без прозы. Используйте свой блог и Twitter для этого.
Начните с заголовка раздела “Как внести вклад” и кратко объясните, что нужно сделать, чтобы создать запрос на вытягивание (pull request) в ваш репозиторий. Представьте, что вы общаетесь с начинающим разработчиком, который даже не знает, что такое Java и Maven (если ваш проект использует их). Объясните, как установить необходимые инструменты, как собрать проект, как вносить изменения, как запустить его в режиме горячей перезагрузки (когда изменения отображаются на экране сразу же), как создать форк и что ожидать после отправки форка.
Не увлекайтесь. Стремитесь быть максимально лаконичными. Всегда, где это возможно, направляйте читателя на документацию по этим инструментам или на какие-то блог-посты, которые объясняют лучше. Посмотрите, как это сделано в файле README zold-io/wts.zold.io, веб-приложения, написанного на Ruby. Небольшой текст внизу страницы объясняет, что нужно установить (предоставляя ссылки на учебники по установке), как запустить приложение локально, как запустить сборку, как запустить отдельный модульный тест и что делать, если что-то не работает. Он достаточно лаконичен и, я считаю, понятен.
Вы не хотите, чтобы ваш потенциальный участник отказался. Поэтому этот часть всего README является самой важной. Убедитесь, что ваш текст адресован начинающему программисту, а не вам самим. Как говорят, ваша бабушка должна понять вас здесь.
И не учите нас. Нас не интересует стать экспертами в фреймворках, которые вы используете, или в Docker, который требуется для запуска ваших вещей. Мы просто хотим запустить ваше приложение, внести некоторые изменения, получить новый релиз и уйти. Поэтому, пожалуйста, не говорите мне “сначала вам нужно изучить Docker”. Нет, мне это не нужно. Если бы мне было нужно, я бы уже сделал это сам. Расскажите мне, как использовать его в этом конкретном случае, и не затрагивайте все остальное.
GitHub имеет специальную вкладку “релизы” для этого. Нет необходимости повторять это в README. Просто убедитесь, что ваша вкладка “релизы” содержит достаточно информации и достаточное количество бинарных артефактов для скачивания. Не упоминайте о них ни слова в README.
GitHub автоматически находит ваш файл LICENSE.txt в корневом каталоге вашего репозитория и понимает лицензию. Просто создайте этот файл и не упоминайте в README о лицензии, это лишний шум. Если я хочу узнать, какая лицензия, я знаю, куда нажать.
Это что-то из времени до GitHub. Я бы рекомендовал вам полагаться на вкладку “релизы” и хранить все, что вы хотите нам сообщить, там. Некоторые старые проекты поддерживают журналы изменений, например, вот этот в rubocop-hq/rubocop. Я не думаю, что это хорошая идея.
В каждом репозитории на GitHub есть специальная вкладка, которая называется “contributors”. Нет никакой причины дублировать этот список в файле README. Однако есть одна причина: помочь участникам продвигать себя. В таком случае я рекомендую создать раздел (с заголовком) с названием “Благодарности”, в котором следует перечислить наиболее активных участников со ссылками на их блоги, аккаунты в Twitter и т.д.
Если у вас нет никого, кого следует отметить, не сообщайте нам, кто является участниками. Мы знаем их, об этом говорит GitHub.
P.S. Вот небольшой список README, которые мне нравятся, и которые не принадлежат мне (если вы считаете, что ваш тоже хороший, отправьте его мне по электронной почте, я рассмотрю его и, возможно, добавлю в этот список):
Translated by ChatGPT gpt-3.5-turbo/42 on 2023-12-17 at 15:58
