4

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

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

1 ответ 1

6

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

Вот что он должен включать в себя:

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

У HTTP-сервера Apache простой, но хороший README. Другой хороший пример - README для GNU make, доступный онлайн.

О форматировании:

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

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

Соберём все вместе...

Документация
-------------

GNU make полностью документирован в справочнике по GNU make, который содержится
в этом дистрибутиве как файл make.texinfo. Вы также можете найти он-лайн,
PostScript и DVI версии на сайте FSF. Там же приведена информация о заказе 
документации в печатном виде.

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

Википедия определяет README так:

Файл README (или READ ME), содержит информацию о файлах в папке или архиве и обычно распространяется с ПО.

Википедия перечисляет части README:

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

Ваш ответ

By clicking “Отправить ответ”, you agree to our terms of service and acknowledge you have read our privacy policy.

Всё ещё ищете ответ? Посмотрите другие вопросы с метками или задайте свой вопрос.