07.01.2020

Пишем хорошую документацию для вашей библиотеки с открытым кодом

Важность хорошей документации долгое время незаслуженно недооценивалась на протяжении долгого времени. Даже продукты десятилетней давности в большом количестве не имели хорошей (или хоть какой-то) документации. Кроме, разве что, самых популярных. Разработчики этих библиотек полагали, что нескольких примеров кода будет достаточно, чтобы любой новичок понял идею и смог использовать их наработки в деле.

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

Еще одна причина того, почему разработчики осознали важность документации, состоит в конкуренции библиотек в экосистемах. До наступления эры npm эта проблема не стояла так остро. Например, в Python обычно бывает только один способ сделать что-либо. В JavaScript, до прихода Node, также не было большого числа библиотек, которые выполняли бы одну и ту же функцию разными способами. Вот попытайтесь припомнить какие-нибудь популярные альтернативы jQuery!

А сегодня мы можем выбирать себе технологический стэк. Поэтому разработчики библиотек и фреймворков прилагают значительные усилия, чтобы максимально облегчить потенциальному пользователю изучение и использование их продуктов. JavaScript-разработчики могут выбирать между Angular, React, Vue и другими, менее популярными фронтенд-фреймворками, а также между Express, Koa или Sails в бэкенде. И это еще если не считать миллионы других библиотек, занимающих промежуточное положение!

Из чего состоит хорошая документация

Документация проекта состоит из многих вещей. Например:

• Файл README
• Справочная информация
• Руководство пользователя
• Сборник рецептов
• Посты в блоге

Каждый из этих пунктов служит своим целям, но границы между ними порой бывают размытыми.

README

Файл README это, зачастую, первая возможность потенциальных пользователей познакомиться с вашим продуктом. В нем могут содержаться сведения, характерные для разных типов документации (справочника, руководства и т.п.), но при этом файл README не спутаешь ни с чем другим. Этот файл помогает вам «продать» вашу open-source библиотеку. При этом не забывайте, что текст README должен быть кратким и информативным.

Начните с того, для чего вообще предназначена ваша библиотека, какие проблемы пользователей она решает. Можно привести примеры распространенных случаев использования. Хорошо написанный первый абзац это отличный старт для любого README-файла.

Если ваш файл длиннее одной или полутора страниц, будет хорошим тоном добавить содержание (список контента).

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

Наконец, включите в ваш файл README сведения о лицензии продукта и список контрибьюторов. Можно также добавить параграф о том, как принять участие в разработке вашей библиотеки. Помните, что одним из столпов open-source является уважение ко времени других людей. Если ваши потенциальные контрибьюторы смогут быстро разобраться в работе вашей библиотеки, от этого выиграют все.

Справочная информация

Справочные материалы это, пожалуй, самая техническая часть вашей документации. Ее предназначение — перечислить весь список функций вашей библиотеки, их ожидаемые input-ы, output-ы и побочные эффекты, а также назначение и примеры реализации. Примеры в справочнике должны быть максимально изолированными и самодостаточными.

Справочная информация часто генерируется автоматически. Также есть много инструментов для упрощения обновления справочника и для облегчения работы с ним. Но не следует забывать, что справочные материалы, полностью сгенерированные компьютером, могут быть сложны для восприятия пользователями. Нужно постараться включать хоть по одному предложению «от себя» в каждом пункте справочной информации.

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

Руководство пользователя

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

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

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

Когда пишете руководство, попробуйте представить, что перед вами сидит группа людей и вам нужно объяснить им работу вашего продукта. Помните, что по части объяснений лучше перестараться, чем оставить какие-то концепции неразобранными — так вы проявите большее уважение к пользователям.

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

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

Сборник рецептов

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

Сборник рецептов не является обязательной частью документации для небольших и специализированных библиотек. Добавлять его имеет смысл, только если объяснение концепций более сложное, чем приемлемо для текста руководства. В таком случае сборник рецептов можно рассматривать как собрание коротких туториалов по достижению желаемого результата.

Говоря о различиях руководства пользователя и сборника рецептов, следует упомянуть еще об одном аспекте. Руководство, главным образом, фокусируется на вашей собственной библиотеке. А в сборнике рецептов вполне могут быть ссылки на другую документацию, а также демонстрация интеграции с другими библиотеками. Кроме того, вы можете даже объяснить, почему отдаете предпочтение одним функциям языка перед другими. Это помогает пользователю лучше понять не только вашу библиотеку, но и язык программирования в целом.

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

Посты в блоге

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

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

Учтите, что несмотря на название раздела, это может быть не пост в блоге в буквальном смысле. Вы можете сделать все вышесказанное на GitHub Gist и поместить ссылку в файл README.

Перед публикацией

Вычитка документации обязательна. Чтение документации с грамматическими и пунктуационными ошибками быстро утомляет. Обдумайте возможность дать вычитать вашу документацию носителю английского языка или кому-то, кто хорошо знает этот язык. Если этот вариант недоступен, дайте возможность вашим контрибьюторам делать пул-реквесты по документации и отдельно попросите их об этом в README. Также к вашим услугам большое количество автоматизированных инструментов, например, Grammarly или Hemingway.

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

Заключение

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

Ну и, в конце концов, писать документацию не так уж и страшно!

Источники:

1. techrocks.ru