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