Представляем вам перевод третьей статьи из серии «Собственный open source проект» — «Open Source Series: Documentation». Для тех, кто не читал предыдущие, вот список:
- Собственный open source проект. Часть 1: с чего все начинается
- Собственный open source проект. Часть 2: начало нового проекта
Первые две статьи цикла предназначались для людей, обдумывающих возможность создания собственного проекта. Я хотел, чтобы люди понимали, чего следует ждать, а также знали, какими должны быть их первые шаги в мире open source.
Эта статья пригодится не только людям, планирующим начать собственный проект, но и людям, которые уже поддерживают таковой.
Для целей этой статьи мы исходим из того, что у вас уже есть open source проект, он доступен на GitHub и его легко можно получить при помощи какого-нибудь реестра пакетов.
Итак, приступим
Проект с открытым исходным кодом, не имеющий документации, это мертвый проект.
Он мертв, потому что никто не захочет погружаться в разбор вашего кода, чтобы понять, как его можно использовать. И дело даже не в том, что без документации людям не понятно, как пользоваться проектом, дело в том, что без нее никто даже не будет знать, для чего вообще предназначен ваш проект.
В общем, «для чего?» и «как?» это и есть два основных вопроса, ответы на которые должны содержаться в вашей документации проекта. Это ее основа и обязательная часть.
Описание
Описание проекта это первое, что видит любой посетитель GitHub-репозитория. Поэтому хорошее описание должно коротко давать ответ на вопрос «для чего?» в отношении этого проекта. Например:
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, это абсолютный минимум, необходимый для каждого достойного проекта с открытым исходным кодом.
