Исчерпывающее руководство по написанию README, которое выделяется и заставляет людей восхищаться!
Если вы торопитесь и просто хотите, чтобы шаблон был внизу (не круто).
Остальные крутые люди готовятся сделать свой первый шаг к тому, чтобы стать README MASTER! (абсолютно не кликбейт).
Вы только что создали этот потрясающий проект и поделились им на GitHub. Вы думаете, что теперь просто откинетесь и подождите, пока мир скажет вам, насколько крутой ваш проект. В конце концов, вы в течение последнего месяца неустанно работали над этим очень сложным проектом, верно?
Что ж, давайте сделаем шаг назад и посмотрим с точки зрения разработчика или пользователя, проверяющего ваш проект. Хотя вы знаете, насколько крутым ваш проект и как он собирается решить эту насущную проблему, которая не была решена (пока вы не пришли), человек будет смотреть на ваш проект и задаваться вопросом что в этом мире вы построили.
Если никто не может понять, как использовать ваше программное обеспечение, значит, происходит что-то очень плохое.
Если люди не знают, что делает ваше программное обеспечение, они не будут использовать его или вносить свой вклад в него и, скорее всего, найдут что-то более ясное и лаконичное в море программного обеспечения с открытым исходным кодом.
Вот тут-то и пригодится README!
Хороший README - это лицо вашего проекта. Это первое, на что смотрит человек в вашем проекте, и он дает им очень краткое введение в ваше программное обеспечение.
Красивый и полезный файл README может выделить ваш проект и привлечь внимание сообщества разработчиков.
Это поможет им понять ваш проект, как они могут заставить его работать и почему им следует внести свой вклад.
«Ого, чувак! Хорошая тирада! Если ты так много разбираешься в чём-то, почему бы тебе не рассказать нам, как писать, тогда… »
Эй, я не могу сказать вам, что существует конкретный набор правил, и вы должны следовать этим правилам, не колеблясь в пользу хорошего README.
Это не так.
Я расскажу, как я пишу README для своих проектов с открытым исходным кодом, и о вещах, которые вам следует учитывать при написании README для своих проектов, и вы (надеюсь) сможете получить некоторое представление.
Также помните, что вы не станете мастером README за один день. Как и все остальное, это требует практики.
Я уже некоторое время участвую в разработке ПО с открытым исходным кодом и заметил одну вещь: все великие проекты имеют Awesome README.
Вы находитесь на странице проекта, и через несколько минут вы готовы к работе со своей версией проекта.
Есть много участников, много запросов на вытягивание, обновленные версии, которые выпускаются часто, и все они имеют общий фактор - отличный README. .
Новый разработчик сможет найти все подробности, чтобы начать работу, например инструкции по установке и руководства для участников.
Новый пользователь сможет узнать, как используется проект, с помощью информативных снимков экрана и демонстраций.
«У меня нет на это времени, покажи мне уже README!»
Хорошо, хорошо, хорошо (извини, что я пошел немного МакКонахи).
Вот файл README для моего проекта NSFW Фильтр. Я думаю, что это лучший README, который я написал.
Я рассмотрю различные части README, которые я думаю важны для каждого README.
Вот ссылка на файл README, использованная в этом примере. Вы также можете найти файл README шаблона, который вы можете напрямую скопировать и вставить в свои проекты.
Что ж, на этом все кончено.
Я прощаюсь, мой кузнечик, этими напутственными словами (мудрости) от README Sensei (оповещение о новом твиттере!).