Пишем документацию для JavaScript-проекта

0
194
views

Перевод статьи «Writing documentation for your JavaScript project».

Написание документации проекта

Современные разработчики крайне редко строят что-то с нуля. Ваша обычная работа состоит, главным образом, из интеграции различных JavaScript-библиотек. Если вы создаете веб-приложение, для вашего фронтенда вы скорее всего будете использовать какой-нибудь фреймворк, например React, Vue или Angular. Для передачи и управления данными вы будете пользоваться Redux или GraphQL. Что касается бэкенда, у вас будет Express и, возможно, Loopback. Затем вам нужно покрыть все это тестами, так что Jest, Mocha или Jasmine также будут задействованы в процессе. Наконец, будут еще и UI-фреймворки, такие как Bootstrap, и, возможно, какие-то инструменты для визуализации графиков. Я уже перечислил как минимум 7 основных библиотек, и это лишь для простого проекта! А как насчет технологий, лежащих в основе всей вашей разработки, таких как сам JavaScript, Node.js и, вероятно, Typescript? Да, у вас будет много всего!

Как вы изучаете все эти инструменты? Конечно, с помощью документации.

Почему документация так важна?

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

Если ваш проект не имеет хорошей документации, люди не будут даже рассматривать возможность его применения

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

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

Естественно, никакой бизнес, никакие корпорации не будут использовать библиотеку, не имеющую документации. Какой председатель правления или технический директор стал бы рисковать ресурсами своей компании, тратя их на технологию, для освоения которой понадобится непредсказуемое количество времени? Больше того: даже инженерам Facebook было бы сложно поддерживать кодовую базу этого проекта, потому что –

Через 6 месяцев вы сами не будете понимать свой код

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

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

Документация улучшает код

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

Что нужно писать в документации?

Что нужно писать в документации

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

Определение аудитории

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

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

Какую проблему решает ваш проект

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

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

Чтобы посмотреть образец правильно написанного названия и описания, можно заглянуть на страницу Sing App React Admin Template documentation.

Документация Sing App React Admin Template

Быстрый старт и шаги инсталляции

Большинство людей не любят ждать. И ваши пользователи в том числе. Поэтому дайте им возможность как можно быстрее запустить и испытать ваш проект. Подготовьте простой короткий список шагов, необходимых для установки и настройки, и поместите его вверху первой страницы документации. Обычно такой список представляет собой набор команд, необходимых для установки и запуска. По возможности следует сделать так, чтобы для запуска приложения (подключения библиотеки) пользователь мог просто скопировать и вставить эти команды. В качестве примера можно привести Rails Admin documentation:

Шаги инсталляции

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

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

Документация компонентов и функционала

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

Первое, что нужно сделать, это составить список всех таких компонентов и на его основе создать содержание со ссылками на соответствующие страницы.

Для каждой отдельной части вашей документации лучше всего применять тот же принцип, что и для документации проекта в целом: назвать компонент, указать, для чего он используется, описать процесс инсталляции (если нужно).

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

Документация Firebase

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

Лицензия и инструкции для контрибуторов

Должно быть что-то, регулирующее отношения между вашим проектом и пользователем. Вам нужно решить, при каких условиях ваше ПО может использоваться и распространяться. В интернете можно найти множество разных вариантов лицензий, вам нужно только выбрать подходящую для вас. Самые популярные варианты лицензий – BSD, MIT, Apache GNU. Имейте в виду, что это лицензии open source. Проприетарные лицензии варьируются от проекта к проекту, так что это отдельная тема.

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

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

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

Советы по написанию документации

Мы не можем предугадать все use cases и способы, которыми пользователи будут использовать вашу документацию. Общий принцип – продолжать ставить себя на место пользователя и пытаться все организовывать именно с такой точки зрения. Но есть некоторые советы, применимые в любой документации:

  • Люди будут просто копировать и вставлять ваш код. Имейте это в виду, так что проверьте все дважды, скопировав код и запустив его. Старайтесь не помещать никаких невидимых символов в примеры кода. Для встраивания блоков кода лучше пользоваться тегами code и blockquote.
  • Следите за обновлением документации. Каждое изменение в коде должно сопровождаться соответствующим изменением в документации. В противном случае она быстро устареет, а устаревшая документация это все равно что вообще отсутствующая.
  • Комментарии в коде это часть документации. Причем очень важная. Если ваш проект имеет открытый исходный код, пользователи будут его читать, а значит, встроенные комментарии будут им очень полезны. Кроме того, есть специальные инструменты, такие как JSDoc, генерирующие документацию на основе комментариев в коде! Таким образом вам даже не придется ничего писать в отдельном файле. Просто «скормите» этому инструменту вашу кодовую базу и – вуаля! – у вас есть готовая документация.

Инструменты, ускоряющие процесс

Инструменты для генерации документации

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

Итак, давайте посмотрим, какие инструменты нам доступны в 2019 году.

JSDoc

JSDoc это популярный генератор документации для JavaScript. Все, что нужно сделать, это запустить команду jsdoc с именем файла в качестве аргумента. Вот и все. Программа сгенерирует готовый к использованию HTML-файл. Сайт JSDoc – https://github.com/jsdoc/jsdoc.

Docusaurus

Docusaurus это более сложный инструмент, позволяющий вам сгенерировать целый веб-сайт. Этот проект основан на React и поддерживает версионирование, благодаря чему вы сможете с легкостью обслуживать различные версии документации, сгенерированные в прошлом. Другое существенное преимущество Docusaurus – встроенный поиск и поддержка многоязычности, что очень важно для популярных репозиториев. Сайт – https://docusaurus.io/.

apiDoc

apiDoc создает документацию из аннотаций API в вашем исходном коде. Это отличный инструмент для генерации документации проекта. В нем можно многое настроить, например, указать параметры, коды ошибок, образцы ответов и т. д. Сайт – http://apidocjs.com/.

Хорошие примеры документации JavaScript-проектов

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

Итоги

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

ОСТАВЬТЕ ОТВЕТ

Please enter your comment!
Please enter your name here