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

#документация

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


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

    

Ответы

Ответ 1

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:


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