Как написать хороший README

Ответ 1

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

Здесь я думаю, что он должен включать:

• название проектов и всех подмодулей и библиотек (иногда они называются разными и очень запутанными для новых пользователей)
• описания всего проекта и всех подмодулей и библиотек
• 5-строчный фрагмент кода о том, как его использовать (если это библиотека)
• информация об авторских правах и лицензировании (или "Читать LICENSE" )
• инструкция по захвату документации
• инструкции по установке, настройке и запуску программ
• чтобы получить последний код и подробные инструкции по его созданию (или быстрый обзор и "прочитать INSTALL" )
• список авторов или "Читать АВТОРЫ"
• для отправки ошибок, запросов функций, отправки патчей, присоединения к списку рассылки, получения объявлений или присоединения к сообществу пользователей или разработчиков в других формах.
• другая контактная информация (адрес электронной почты, сайт, название компании, адрес и т.д.)
• краткая история, если это замена или вилка чего-то другого
• юридические уведомления (crypto stuff)

Apache HTTP Server имеет простой, но хорошо README. Еще один хороший, который я нашел в Интернете, - это GNU Make README.

В соответствии с форматированием я бы сказал, придерживайтесь традиций Unix, насколько это возможно, и/или используйте markdown специально для проектов github, что делает README.md как html.

• Только символы ASCII, если README написан на английском языке
• напишите на английском языке, если это возможно, и отправьте переведенную версию с двухбуквенным расширением кода языка, например README.ja
• 80 символов или меньше на строку
• одиночная пустая строка между абзацами
• тире под заголовками
• отступ с использованием пробелов (0x20) не вкладка

Объединяя все это вместе...

Documentation
-------------

GNU make is fully documented in the GNU Make manual, which is contained
in this distribution as the file make.texinfo.  You can also find
on-line and preformatted (PostScript and DVI) versions at the FSF web
site.  There is information there about ordering hardcopy documentation.

  http://www.gnu.org/
  http://www.gnu.org/doc/doc.html
  http://www.gnu.org/manual/manual.html 

Wikipedia определяет как:

Файл readme (или read me) содержит информацию о других файлах в каталоге или архиве и очень распространен с помощью программного обеспечения.

и в нем указано следующее содержимое:

• инструкции по настройке
• инструкции по установке
• инструкции по эксплуатации
• манифест файла
• информация об авторских правах и лицензировании
• контактная информация для дистрибьютора или программиста
• известные ошибки
• поиск и устранение неисправностей
• кредиты и подтверждения
• журнал изменений

Ответ 2

Я думаю, что большинство README слишком сложны. README - это первый файл, который человек должен прочитать, когда сталкивается с исходным деревом, и должен быть написан как очень краткое, очень простое введение в программное обеспечение. Он должен содержать название кода, версию, возможно последнюю обновленную дату и очень краткий обзор программного обеспечения высокого уровня (очень высокого уровня). И все, кроме, возможно, ссылок на какие файлы содержат другую информацию, которую может заинтересовать человек, например, инструкции по установке (в INSTALL), авторы (в AUTHORS) или история (в ChangeLog или ReleaseNotes).

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

Ответ 3

Это простой текстовый файл (более понятный), называемый "README" (или "readme" или "ReadMe" ), и возможно с расширением ".txt", если ваша ОС делает вас), в котором говорится:

• Что такое readme для (включая версию) как имя, так и краткое описание
• Когда последний файл был отредактирован
• Возможно: кто несет ответственность за это бедствие
• Возможно: информация о лицензировании
• Где бы вы хотели получить описанную вещь, если у вас ее еще нет.
• Что вам нужно запустить или использовать.
• Что вам нужно знать, чтобы это произошло.
• Где найти более полные документы (если есть)
• Что-нибудь еще полезное

Ответ 4

Все приведенные выше ответы относятся к README, созданным для программы/библиотеки. Однако, когда вы создаете Readme для школьного проекта, перспективы разные. В этом случае вы хотели бы выделить следующее:

• Информация об авторе
• Как скомпилировать и запустить вашу программу.
• Общие ошибки при компиляции/запуске программы
• Общий обзор достигнутых функциональных возможностей
• Обсуждение дизайна и ваша реализация
• Любые эмпирические данные, которые вы хотели бы продемонстрировать
• Профилирование ваших результатов (при необходимости)
• Основные узкие места

Надеюсь, что это поможет любому студенту, который должен написать Readme для своего профессора.

Ответ 5

Я также искал некоторые инструкции по форматированию README, особенно "традиционные", с разделами NAME, DESCRIPTION, SYNOPSIS, AUTHORS (пример Man page GNUCHESS).

Одна связанная ссылка, которую я нашел, это: Стиль документации для публикации в формате:

Эти рекомендации предназначены для документирования программных дистрибутивов программного обеспечения с открытым исходным кодом. Они применимы к проектам C, Perl и Java и даже к проектам, которые не содержат компилируемого программного обеспечения. [...]
Любое приложение должно содержать на верхнем уровне следующие файлы документации:... LICENSE [...] НОВОСТИ [...] README [...] TODO
Документация должна, как минимум, включать разделы NAME, SYNOPSIS, DESCRIPTION, ПРИМЕРЫ, АВТОР или АВТОРЫ, а также разделы АВТОРСКОГО ПРАВА И ЛИЦЕНЗИИ в этом порядке. Если у него есть параметры командной строки, также должен быть раздел OPTIONS, следующий за разделом DESCRIPTION. Все они должны быть = head1 в POD.

Теперь, когда упоминается POD, это означает Обычная старая документация для Perl. Я нашел также Стандарты кодирования GNU - 6.9 Man Pages, но он мало говорит о стиле документации.

Я думал, что у меня есть другие аналогичные ресурсы, но я не могу найти их в моем текущем сеансе браузера :/ Если я снова найду, я обязательно обновлю это сообщение...

Ура!

Ответ 6

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

Ответ 7

Я думаю о README, отвечая "Что это такое?"

Что я хочу найти в README:

• Автор
• Дата
• одно предложение, объясняющее, что этот проект
• очень краткое описание содержимого, например: "src содержит исходный код, INSTRUCTIONS объясняет, как скомпилировать"
• Где найти дополнительную информацию

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

Ответ 8

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