1. Почему важна документация?
2. Что писать?
3. Инструменты для ускорения процесса
4. Отличные примеры проектной документации JavaScript
« 5. Резюме"

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

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

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

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

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

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

Вы не сможете понять свой код через 6 месяцев

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

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

Документация - это любовное письмо, которое вы пишете себе в будущем.

- Дэмиан Конвей

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

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

Что писать?

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

Определите свою аудиторию

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

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

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

Заинтересованы в нашей продукции? Вот и сам шаблон администратора Sing App React!

Шаги по быстрому запуску и установке

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

JSDoc

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

Докзавр

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

ApiDoc

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

Отличные примеры документации проекта JavaScript

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

Резюме

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

О Flatlogic

В Flatlogic мы разрабатываем веб-шаблоны и мобильные шаблоны. Мы вошли в топ-20 компаний по веб-разработке из Беларуси и Литвы. За последние годы мы успешно реализовали более 50 крупных проектов для малых стартапов и крупных предприятий.
Шаблоны Flatlogic
Примеры использования Flatlogic

Вот небольшой видеоролик о шаблонах Flatlogic, услугах веб-разработки и партнерской программе.

Первоначально опубликовано на flatlogic.com

Flatlogic создает лучшие шаблоны администрирования для Vue, Angular и React с потрясающим дизайном и один из лучших мобильных шаблонов для React Native.