Собственный open source проект. Часть 3: документация

Представляем вам перевод третьей статьи из серии «Собственный open source проект» — «Open Source Series: Documentation». Для тех, кто не читал предыдущие, вот список:

Первые две статьи цикла предназначались для людей, обдумывающих возможность создания собственного проекта. Я хотел, чтобы люди понимали, чего следует ждать, а также знали, какими должны быть их первые шаги в мире open source.

Эта статья пригодится не только людям, планирующим начать собственный проект, но и людям, которые уже поддерживают таковой.

Для целей этой статьи мы исходим из того, что у вас уже есть open source проект, он доступен на GitHub и его легко можно получить при помощи какого-нибудь реестра пакетов.

Итак, приступим

Проект с открытым исходным кодом, не имеющий документации, это мертвый проект.

Он мертв, потому что никто не захочет погружаться в разбор вашего кода, чтобы понять, как его можно использовать. И дело даже не в том, что без документации людям не понятно, как пользоваться проектом, дело в том, что без нее никто даже не будет знать, для чего вообще предназначен ваш проект.

В общем, «для чего?» и «как?» это и есть два основных вопроса, ответы на которые должны содержаться в вашей документации проекта. Это ее основа и обязательная часть.

Описание

Описание проекта это первое, что видит любой посетитель GitHub-репозитория. Поэтому хорошее описание должно коротко давать ответ на вопрос «для чего?» в отношении этого проекта. Например:

React:

A declarative, efficient, and flexible JavaScript library for building user interfaces. («Декларативная, эффективная и гибкая JavaScript-библиотека для создания пользовательских интерфейсов»).

Чтобы редактировать описание, нужно кликнуть кнопку «Edit» в верхнем правом углу вашего репозитория:

README.MD

README.MD это файл в корневом каталоге вашего проекта, написанный с использованием синтаксиса Markdown. Этот файл содержит всю информацию о вашем проекте, которая может понадобиться посетителю репозитория.

Файл README должен содержать детальное описание проекта (ответ на вопрос «для чего?») и очень подробные инструкции по его использованию (ответ на вопрос «как?»). Эти инструкции должны затрагивать каждую часть публичного API, желательно — с примерами использования.

Несколько советов по написанию хорошей документации API:

Придерживайтесь простоты.
Чем проще API и приведенный пример, тем легче пользователю понять, что он делает и как его использовать.
Не забывайте о структурировании.
Используйте один шаблон и одинаковую визуальную структуру для каждого метода API.
Будьте пользователем.
Всегда пишите описание API с точки зрения пользователя. Встаньте на его место и предположите, что вы ничего не знаете об этом API и все, что у вас есть, это документация.
Обновляйте сведения.
По мере развития проекта API могут меняться. Следите за тем, чтобы файл README всегда содержал самые актуальные API и примеры.

README может содержать следующие вещи (хотя это уже не обязательно):

ссылку на руководство для контрибьюторов;
список контрибьюторов;
ссылку на журнал изменений проекта (change log);
информацию о последней версии;
информацию о лицензии;
сведения о статусе сборки;
счетчик загрузок;
ссылку на чат для быстрой обратной связи.

Бейджи

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

Вообще есть широкий выбор источников бейджей, но я советую пользоваться shields.io: там есть значки буквально для чего угодно.

Добавить бейдж в свой файл README очень просто:

Переходите по ссылке shields.io.
Выбираете подходящую категорию.
Кликаете на бейдж, который хотите добавить в ваш README.
Заполняете необходимую информацию (если нужно).
В выпадающем меню выбираете «Copy Markdown».
Вставляете скопированное в ваш файл README.

Бейджи обычно располагаются вверху файла README, прямо перед подробным описанием. Вот как это выглядит:

Тесты

Справка по API это хорошо, но ничто не сравнится с настоящим кодом, где используются ваши публичные API.

Один из лучших способов дополнить вашу документацию — иметь хорошее покрытие кода описательными тестами. Иногда тесты объясняют код лучше любой документации.

Итоги

В этой части мы затронули только самую основную документацию. На самом деле в ней может быть не только README или описание проекта. Например, по мере роста проекта и появления каких-то проблем (issues) последние становятся неотъемлемой частью документации.

Но файл README, описывающий публичный API, это абсолютный минимум, необходимый для каждого достойного проекта с открытым исходным кодом.

[customscript]techrocks_custom_after_post_html[/customscript]

[customscript]techrocks_custom_script[/customscript]