Что такое README?

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

✔ Ридми, Readme - перевод

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

что значит Readme перевод? Этот термин состоит из двух слов "Read" и "Me", первое можно перевести, как "читать", а второе, как "меня".

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

В некоторых случаях (часто вместе с текстовой версией) файл может быть представлен в HTML (readme.html) или другом формате (например, RTF [readme.rtf] или Microsoft Word [readme.doc] в Microsoft Windows). С ПО для DOS расширение DOC использовалось и для текстовых файлов.

Файл README обычно включает в себя:
информацию о системных требованиях
инструкции по установке программы
инструкции по настройке
инструкции по управлению программой
информацию о лицензии и авторском праве
контактную информацию — как связаться с автором и/или распространителем
известные ошибки (иногда выносится в файл BUGS)
инструкции по устранению неполадок
сведения об авторах и благодарности
протокол изменений программы (обычно выносится в файлы типа ChangeLog и NEWS).

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

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

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

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

README

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

Пишите его на английском языке, если это возможно, и добавляйте файл с переведенной версией. Добавляйте к такому файлу расширение из двух букв, соответствующее языку, например README.RU

В строке должно быть не более 80 символов.

Обязательно оставляйте одну пустаю строку между абзацами.

подчеркивайте строку заголовка символами “минус”.

для отступов используйте пробел (0x20), а не табуляцию.

Важно знать! Некоторые вирусы, могут так же находиться в этом файле, обратите внимание на расширение "readme.txt", это правильный, а "readme.com" или "readme.exe", это скорее всего вирус. Проявите внимательность, чтобы вам не внедрили вредоносный код, ибо это чревато.
• Считаете информацию полезной? Поделитесь с друзьями в соц. сетях, выскажете свое мнение в комментариях.

Внимание! Остались вопросы после прочтения статьи или есть что сказать? Оставляйте свои комментарии:

► Оставить коментарий:

Имя: Ваш вопрос:

Леонид Пивторак (Администратор.)
 Ответ на вопрос:

Pубрики:


^НАВEPХ^
Любое копирование материала без указания источника Пивторак.рф запрещено!