Кто читает README?

Тебе случалось попадать из поиска Google/Yandex на страницу GitHub? Перед погружением в документацию хочется понять куда ты попал, нужно оно тебе или нет. Как раз на этот случай пишут README — для тех кто случайно нашел репозиторий на GitHub и хочет быстро сориентироваться на месте.

Документацию составляют в формате Markdown и кладут в специальный файл README.md рядом с кодом. Ознакомиться с языком разметки Markdown можно на GitHub Guides.

Что должно быть в README

Каждый проект особенный, однако есть несколько типичных разделов документации:

1. Короткое описание проекта

Для тех, кто заблудился, оставляют вводное слово о проекте. Просто и доходчиво объясняют в чем польза от этого кода.

2. Требования к окружению

Обычно здесь указывают тип операционной системы или минимальную версию интерпретатора Python. Для сайтов —важно знать поддерживаемые версии браузеров и формат устройств: мобильники, планшеты или desktops.

3. Как установить

Раздел отвечает на вопрос “Что нужно сделать перед запуском программы?” и содержит инструкции по развертыванию проекта. Самый удобный формат — это команды bash с коротким пояснением к ним. Пользователь копирует команды в консоль и быстро их запускает.

Для кода и команд bash есть специальный способ форматирования в Markdown. Выглядит так:

for movie in movies:
    print(movie['name'])

$ python3 grab_movies.py -l 10 --quiet
Тачки 3 - 20 кинотеатров
Новый Терминатор - 100 кинотеатров
....

Оформленный код попадается на глаза даже при беглом чтении, что крайне удобно.

4. Примеры запуска скриптов

Если речь идет о консольной утилите, то полезно показать как в консоли выглядит результат работы скрипта в случае штатной ситуации.

Если у проекта есть скрипты c тестами или другие инструменты для разработчиков, то об этом тоже полезно написать, привести примеры их запуска.

5. Примеры использования программного API

Если проект поставляется в виде библиотеки и используется из других скриптов посредством import, то стоит описать доступные функции, классы и константы. Нагляднее всего получается это сделать на примерах кода, поэтому их должно быть много.

Если проект большой, то документацию часто выносят на отдельный сайт с удобной навигацией и поиском. Часто используют сервис Read the Docs.

Примеры для подражания

На GitHub полно проектов с хорошей документацией. Всегда можно подсмотреть что-то для себя:

• Mimesis
• Flask
• Requests
• Python Slugify

А еще существуют готовые шаблоны README. Вот несколько на выбор:

• A template to make good README.md
• README.md template

Понятные ссылки

Ссылки в документации должны быть говорящими и осмысленными. Вот плохой пример:

This is a code of [this site](http://mysite.devman.org).

# Deploy

... more details can be found [here](http://bit.ly/2urHet7)

... then open a browser and go to this [link](http://localhost:5000/).

Из текста сложно понять о чем идет речь, приходится в обязательном порядке кликать либо наводить курсор на ссылку. Слова “там”, “здесь”, “ссылка” и подобные им не привносят нового содержания, и при этом скрывают адрес. Как это исправить:

This is a code of site [mysite.devman.org](http://mysite.devman.org).

# Deploy

... more details can be found
    in discussion [Accessing variable in outer scope](http://bit.ly/2urHet7) on Stackoverflow

... then open a browser and go to [localhost:5000](http://localhost:5000/)

Что еще следует знать

На сайте GitHub есть специальный текстовый редактор с возможностью предпросмотра еще до коммита. Получается быстро и удобно.

Экспериментировать с оформлением документации удобно на сайте GitHub

Другой способ — это установить плагин для Sublime Text OmniMarkupPreviewer.

Блоки кода в документации очень важны. Чтобы их проще было найти, их выделяют специальным форматированием.

Код в документации должен быть оформлен как вставка кода в Markdown

Совсем здорово получается когда явно указан язык программирования и корректно работает подсветка синтаксиса. Чаще всего документацию просматривают бегло и рассчитывают на общепринятый стиль оформления. Вычитывать огромное полотно плохо форматированного текста никто не будет — всем лень.

Документация должна быть лаконичной. Писать следует только о действительно важных вещах, коротко и по делу. Поэтому меньше слов, больше примеров.

Документацию надо стараться писать на английском. Потому что над OpenSource проектами работают люди из разных стран, и документация на английском — это стандарт.

Eще по теме:

• У меня маленький проект для себя. Зачем ему ридми?