Как написать качественный README

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

Написание README проекта похоже на написание предисловия к книге: хороший проект должен иметь не только качественный код, но и качественный документ. Для пользователей хороший документ может сэкономить много времени.

глобализация

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

Ведь документ на родном языке имеет более интимное ощущение, и в то же время его будет легче читать.

Например, документация Ant Design Pro:

что за проект

Прежде всего, у вас должно быть название проекта, оно не должно быть властным, но оно должно быть запоминающимся, не слишком сложным для чтения и не слишком длинным.

Например мел, реагировать, vue, командир и т.д. Если вы действительно не знаете, с чего начать, создайте случайную функцию и испытайте удачу.

Конечно, если у вас есть ЛОГОТИП, это лучше всего.Большой ЛОГОТИП высокой четкости выглядит красиво и выглядит удобно.

Именно так:

или это:

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

• На каком языке она написана? Node, Python или что-то еще
• Какова цель этого проекта
• Информация о последней версии
• Сборка, результаты испытаний и т.д.
• Демо демо адрес или официальный сайт

так:

Для нашего технического README мы должны поставить различные значки на лицо, такие как стандартный travis, покрытие, npm и т. д., чтобы люди чувствовали себя в безопасности.Если вы не тестировали сборку самостоятельно, я не в своей тарелке. Вы можете проверить эти вещи здесь:shield.io

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

Например:

Установка и быстрый старт

Эта часть контента является важной частью документа. Благодаря этим шагам пользователи могут быстро его использовать.

Во-первых, вам нужно сообщить пользователю, как получить и инициализировать элемент, например:

Затем вам нужно дать простой пример, пусть пользователь быстро почувствует преимущества использования его:

Конечно, в этом месте лучший и наиболее интуитивно понятный способ — поместить изображение в формате gif, чтобы привлечь внимание пользователя и показать пользователю результаты, такие как этот:

API

API — это душа проекта. Это самое непосредственное место, доступное пользователям. Если у пользователей возникнут вопросы, они найдут вашу документацию по API как можно скорее.

Что должно быть четко сказано об API:

• эффект
• Входные параметры и необходимость каждого параметра, тип данных и т. д.
• возвращаемое значение

Если у вас немного API, вы можете поместить их в файл, но если у вас много API, рекомендуется вынести API в отдельный файл, и вы можете оставить ссылку на этот файл.

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

Так:

изменение версии

Также лучше иметь документ CHANGELOG, какие изменения были внесены в разные версии, какие функции и т. д., чтобы пользователи знали, что сделала каждая версия.

Так:

FAQ

Конечно, если вы не хотите отвечать на повторяющиеся вопросы, я думаю, вам нужен FAQ, чтобы задокументировать некоторые распространенные вопросы.

способствовать

Я считаю, что многие люди, как и я, гордятся тем, что отправляют PR в некоторые известные репозитории.

Итак, если вы можете предоставить способ или способ отправки PR, вы можете привлечь больше людей для написания кода и в то же время показать участников, я думаю, что больше людей захотят внести свой вклад.

Например, было бы интересно иметь такой список:

Авторские права

Я считаю, что не так давно инцидент с соглашением об открытом исходном коде Facebook известен всем, и это также было много шума.Поэтому вы должны быть осторожны с вопросами авторского права, такими как соглашения с открытым исходным кодом.Если то, что вы хотите сделать, не является игрушечный проект, то надо об этом четко написать.

Суммировать

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

Но эти основы - это то, что нам всем нужно:

• имя
• Введение
• Функция
• Конфигурация установки
• Краткое руководство
• Документация API

Это моменты, которые будут волновать пользователей, и их следует тщательно обдумать, прежде чем писать.

Это просто когда я занимался какой-то документацией, я проверил много документов, и так много написал, но реальная ситуация может быть очень разной, так что писать ли так, у всех разные мнения!