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

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

  • Что такое README файл?
  • Что я должен писать в нем?
  • Как именно отформатировать его?

Боковое примечание:

В качестве примера, который удовлетворяет "OMG, это отличный README!" а также "OMG this README бесполезен", я разместил ссылку на gnome-cups-manager's README в качестве комментария. Комментарий теперь удален, вероятно, из-за мертвых поэтому я скопировал содержимое this Суть.

ОТВЕТЫ

Ответ 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, и вы можете получить от него хорошую идею. Приветствия.