Элегантные README

Некоторое время назад я написал сообщение в блоге «База открытого кода — это еще не проект с открытым исходным кодом», где я предложил несколько важных качеств хорошего репозитория / проекта с открытым исходным кодом. Одним из них был хорошо написанный файл README. Здесь я постараюсь дать несколько советов о том, как создать хороший файл README и какие ошибки следует избегать. Я надеюсь, что вы найдете это полезным.

Я перечислю все, что вам нужно иметь в README, в порядке отображения этих элементов:

Название и описание

Зачем включать это? Заголовок уже находится в URL вашего репозитория, а описание проекта — в подзаголовке GitHub. Зачем повторяться? Вместо этого начните с логотипа и списка значков сразу после него:

Обратите внимание на пустую строку после логотипа. Не забудьте указать размер изображения в атрибуте height . Вы можете пропустить width , так как для HTML достаточно одного измерения. Не делайте его больше 100 пикселей в высоту.

Значки

Вы нуждаетесь в них, как я уже говорил ранее . Но вопрос в том, как расположить их внутри README. Вы должны поместить не более пяти значков в линию. Затем разделите строки пустой строкой. Посмотрите, как это делается в нашем репозитории zold-io / zold .

Вы должны сгруппировать их как-нибудь по строкам, используя некоторую логику. Я группирую их по уровню технических деталей. Первая строка о CI, покрытии кода, качестве кода. Вторая строка больше касается управления и т. Д. Это зависит от вас, но убедитесь, что все значки, которые остаются в одной строке, имеют одинаковую высоту! Если какой-либо значок имеет высоту, отличную от всего остального, выделите для него собственную линию, но никогда не размещайте два значка разной высоты на одной линии!

Кроме того, помните, что только в нескольких очень специфических случаях (например, на значках) вам разрешается создавать строки длиной более 80 символов. Рассматривайте ваш документ README как часть исходного кода. Сделайте это правильно и элегантно отформатировано. Ширина строки является одним из тех правил форматирования, которые сделают ваш документ лучше. Восемьдесят персонажей. Вот и все.

Что это такое?

Ваш первый абзац после значков должен объяснить, о чем продукт. Обратите внимание: абзац , а не страница текста. Вы должны поместить описание продукта в один абзац. Здесь нет пуль, нет новых строк, нет отступов. Просто простой кусок текста:

Обратите внимание, пока нет заголовков. Просто логотип, несколько строк со значками и какой-то простой текст с описанием товара. Вы можете и должны использовать здесь уценку и указывать читателю на любые соответствующие посты в блоге, видео на YouTube или что-либо еще, но убедитесь, что вы вписываете всю свою идею в один абзац.

Как это использовать?

Затем, опять же, без каких-либо заголовков, вы просто получаете право на то, как я могу использовать вашего ребенка, как полный новичок в этом репо. Я только что открыл эту страницу, потому что мой друг сказал мне, что это здорово, и я хочу понять, стоит ли это того, или я должен закрыть это прямо сейчас. Вы привлекли мое внимание еще на 60 секунд. Подскажите как это попробовать ! Что-то вроде этого:

Обратите внимание на форматирование. Я ничего не отступаю и использую тройной апостроф для форматирования кода. Вы должны сделать то же самое. Разделите текстовые блоки одной пустой строкой.

Случаи применения

Здесь начинается тело вашего README. Точное содержание зависит от вашего конкретного бизнес-кейса и характера вашего продукта. Тем не менее, независимо от того, что продукт, есть несколько рекомендаций.

Во-первых, не заменяйте автоматически сгенерированные Javadoc (или что-либо еще на вашем языке) на README. README — это не пользовательская документация для всего, что есть в вашем репо. Есть и другие места для этого. Здесь вы можете объяснить несколько наиболее интересных вариантов использования. Посмотрите, как мы это сделали в проекте yegor256 / take .

Во-вторых, начинайте каждый сценарий использования с заголовка второго уровня ( ## в Markdown) и старайтесь избегать заголовков третьего уровня ( ### ). Нужно ли говорить, что четвертый уровень абсолютно запрещен? И, конечно же, снова без отступов. Всегда начинайте свои текстовые строки с крайней левой позиции, независимо от того, является ли это абзацем текста или заголовком раздела.

В-третьих, имейте в виду, что вы очень скоро поменяете свой продукт, и вы не хотите всегда помнить, где в файле README нужно что-то менять. Вы хотите, чтобы ваш README оставался как можно короче и как можно более высокого уровня. Вот почему, если вы можете, избегайте конкретных деталей и вместо этого перенаправьте читателя на соответствующие части автоматически сгенерированной документации.

В-четвертых, используйте как можно меньше слов. Никто не заинтересован в том, чтобы читать вашу прозу дольше нескольких секунд и только для того, чтобы понять, как использовать ваш продукт или как внести некоторые изменения. Не зацикливайся на себе, мы не заботимся о тебе. Сосредоточьтесь на нас и наших потребностях. Расскажите нам, как это работает, и назовите его README. Нет философии, нет прозы. Используйте свой блог и Twitter для тех.

Как внести свой вклад

Начните с заголовка раздела «Как внести свой вклад» и кратко объясните, что нужно сделать, чтобы создать пул-запрос к вашему репо. Представьте, что вы разговариваете с начинающим разработчиком, который даже не знает, что такое Java и Maven (если ваш проект использует их). Вы должны объяснить, как установить правильные инструменты, как построить проект, как внести изменения, как запустить его в режиме горячей перезагрузки (когда я делаю изменения и сразу вижу их на экране), как создать вилка, и что ожидать, когда вилка будет представлена.

Не будь слишком многословным. На самом деле, будьте как можно компактнее. Всегда, когда это возможно, перенаправляйте читателя к документации по этим инструментам или некоторым постам в блоге, которые объясняют лучше. Посмотрите, как это делается в README zold-io / wts.zold.io , веб-приложения, написанного на Ruby. Небольшой фрагмент текста в нижней части страницы объясняет, что вам нужно установить (предоставляя ссылки на руководства по установке), как запустить приложение локально, как запустить сборку, как выполнить одиночный модульный тест и что делать если это не сработает. Это довольно компактно и, я думаю, легко понять.

Вы не хотите, чтобы ваш потенциальный вкладчик ушел. Вот почему эта часть всего README является наиболее важной. Убедитесь, что вы адресуете свой текст младшему программисту, а не себе. Как говорится, ваша бабушка должна быть в состоянии понять вас здесь.

И не учи нас. Мы не заинтересованы в том, чтобы стать экспертами в фреймворках, которые вы используете, или в Docker, что необходимо для запуска ваших вещей. Мы просто хотим запустить ваши вещи, внести некоторые изменения, получить новый релиз и уйти. Поэтому, пожалуйста, не говорите мне: «Во-первых, ты должен изучить Докер». Нет не знаю Если бы я это сделал, я бы сделал это сам. Подскажите, как использовать это в этом конкретном случае , и избавьте меня от всего остального.

Загрузки и релизы

GitHub имеет специальную вкладку «релизы» для этого. Не нужно повторять это в README. Просто убедитесь, что ваша вкладка «релизы» содержит достаточно информации и достаточно двоичных артефактов для загрузки. Не говорите ни слова о них в README.

Лицензия

GitHub автоматически находит ваш файл LICENSE.txt в корневом каталоге вашего репозитория и понимает лицензию. Просто создайте этот файл и ничего не говорите в README о лицензии, это просто чистый шум. Если я хочу знать, что такое лицензия, я знаю, где щелкнуть.

Изменения

Это что-то со времен до GitHub. Я бы порекомендовал вам воспользоваться вкладкой «релизы» и оставить там все, что вы хотите рассказать нам. Некоторые старые проекты поддерживают журналы изменений, например, этот в rubocop-hq / rubocop . Я не думаю, что это хорошая идея.

Авторы против Благодарности

GitHub имеет специальную вкладку в каждом репозитории, которая называется «участники». Нет абсолютно никакой причины воспроизводить список в файле README. Тем не менее, есть одна причина: помочь авторам продвигать себя. В таком случае я бы порекомендовал создать раздел (с заголовком) под названием «Благодарности», в котором должны быть перечислены наиболее активные участники, с их URL-адресами в блогах, учетными записями в Twitter и так далее.

Если у вас нет никого, кто бы это признал, не шумите, рассказывая нам, кто участвует. Мы знаем их, говорит нам GitHub.

PS. Вот краткий список README, которые мне нравятся, но они не мои (если вы думаете, что ваш тоже хороший, напишите мне, я его рассмотрю и, возможно, добавлю в этот список):

• список на данный момент пуст 🙁