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

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

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

Вы готовы? Давайте погрузимся!

Основы документации React

1. Стандартизируйте документацию как процесс в вашей организации.

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

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

  • Используйте согласованный формат для документирования кода, такой как Markdown, reStructuredText, AsciiDoc или любой другой формат, основанный на поддержке инструментов и совместимости с вашей средой разработки.
  • Создавайте стандартизированные шаблоны документации для разработчиков — устанавливайте четкие и краткие рекомендации, описывающие, как следует документировать код, включая соглашения для описания компонентов, ловушек, глобальных хранилищ, служебных функций и других сущностей.
  • Документация, предназначенная для других заинтересованных сторон (менеджеров проектов, клиентов или исполнительных команд), должна давать общий обзор цели и ключевых характеристик рассматриваемого компонента/функции, подчеркивать его ценностное предложение, а также намечать его сроки, основные вехи, ключевые Практические результаты.

Продвиньте эту идею еще дальше, стандартизировав документацию как процесс в вашей организации:

  • Сделайте документацию частью процесса проверки кода, гарантируя, что новые функции или изменения всегда сопровождаются обновленной документацией, предотвращая пробелы в знаниях среди членов команды.
  • Сделайте документацию обязательным результатом. Новые компоненты/функции/служебные функции должны иметь сопроводительную документацию, прежде чем кто-либо сможет их зафиксировать и развернуть. Разработчики в вашей команде не должны иметь возможности закрыть задачу, если их изменения или дополнения в документации не прошли рецензирование.
  • Поддерживайте историю изменений («журнал изменений»), в которой отслеживаются изменения, внесенные в документ с течением времени. Если вы используете подход «документы как код» и коммитите документацию вместе с кодом, это можно сделать просто через журнал Git.

Если вы не хотите слишком много думать, уже есть стандарты, которые можно использовать, и такие инструменты, как IDE, будут анализировать этот синтаксис и предоставлять вам дополнительные функции (например, IntelliSense, улучшенные страницы документации и т. д.). Одним из таких стандартов является JSDocs, один из наиболее часто используемых и с ним очень легко начать работу.

2. Помните, что «документация» — это не просто комментарии к коду.

Комментарии к коду, конечно, могут сказать разработчикам, что делает компонент, но говорят ли они им, что происходит под капотом («как»), когда этот компонент выполняет рендеринг и выполняет свою работу? Говорит ли им, почему ваша компания (или ее ведущий инженер) решила реализовать это именно так, используя эти библиотеки, а не иначе архитектурно?

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

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

Понравилось ли вам то, что вы прочитали? Подпишитесь на мой БЕСПЛАТНЫЙ информационный бюллетень, где я делюсь со всеми своим 20-летним опытом работы в ИТ-индустрии. Присоединяйтесь к Бродяге старого разработчика!

3. Сделайте документацию легко доступной, актуальной и доступной для поиска.

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

Так что помните эти 3 слова при разработке документации для вашего проекта React:

  • Доступность.Документация должна быть под рукой, когда и где она больше всего нужна вашим разработчикам. Альтернативой было бы заставить их перепроектировать код (если он доступен), чтобы ответить на их вопрос. Был там, сделал это, я бы предпочел прочитать документы, спасибо!
  • Обновление: документацию необходимо поддерживать в актуальном состоянии, чтобы не возникало расхождений с кодовой базой. Ваш код изменился? Затем обновите документацию в рамках того же процесса выпуска. Устаревшая документация является неверной информацией и может привести к техническим сбоям, которые в конечном итоге нанесут ущерб вашей прибыли.
  • Возможность поиска. Главное, чтобы разработчики могли как можно скорее найти нужную информацию. На что это похоже? Это зависит. Это может означать разбиение документации на более мелкие подразделы, которые очень легко найти. Это может означать ссылки между релевантными/связанными документами. Это также может означать добавление функции поиска, такой как Algolia, которая отлично работает с бесплатным уровнем и обеспечивает мгновенный полнотекстовый поиск.

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

4. Используйте наглядные пособия и игровые площадки с интерактивными компонентами

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

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

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

Такие инструменты, как draw.io (мой любимый инструмент!), Whimsical, PlantUML и Схемы русалок упрощают создание наглядных пособий, которые добавляют дополнительный уровень понимания вашей документации.

Еще лучше — интерактивная игровая площадка компонентов стоит тысячи фрагментов кода.

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

5. Инвестируйте в инструменты для документации

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

Генераторы документации

Зачем писать все с нуля, если можно немного помочь? React Docgen — это решение для автоматической генерации документации React, созданное самой командой React. Он может читать ваши компоненты React, анализировать как обычные комментарии, так и комментарии в стиле JSDoc, и выводить файл JSON, который можно использовать с инструментами создания статических сайтов, такими как Docusaurus или Astro, которые имеют отличную поддержку стандарта Markdown, обеспечивают настраиваемые шаблоны, красивые темы и простая навигация — для развертываемой версии ваших документов.

Если ваши компоненты представляют собой сложные пользовательские интерфейсы, которые заканчиваются сотнями уникальных состояний, которые вызывают различное поведение, вам может понадобиться решение, такое как React Styleguidist или Docz, которое может автоматически генерировать страницы документации для каждого компонента из комментариев JSDoc. , с активной интерактивной версией компонента, встроенной в сами документы через MDX.

Документация, связанная с кодом, прямо в самой IDE

Если вы ищете единый инструмент, который применяет все, что мы рассмотрели до сих пор, то вам лучше всего подойдет Swimm.

Swimm — это решение для управления знаниями, которое не зависит от языка. Недавно они выпустили плагин IDE (для IDE VSCode и JetBrains), который позволяет вам писать внутреннюю документацию во время написания кода, выбирая фрагменты кода прямо из исходного кода и добавляя их в документы, которые вы пишете в простом Markdown, дополняя их диаграммами Mermaid, гиперссылками, изображениями и видео.



Плагин Swimm IDE: упрощенная документация. Прямо из вашей IDE.
Более эффективная навигация и понимание вашей кодовой базы. Легко находите документы, которые отображаются рядом с соответствующим кодом на…swimm.io





Swimm — Visual Studio Marketplace
Расширение для Visual Studio Code — Непрерывная документация в вашей IDEmarketplace.visualstudio.com



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

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

Вот пример:

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

А в левой части экрана я могу искать документы прямо из IDE, что тоже очень здорово.

В конце концов, им удалось интегрировать процесс документирования в рабочий процесс разработки. Честно? Я люблю это!

Вот основные преимущества использования такого решения:

  • Документация и код связаны. В Swimm вы используете живые фрагменты кода для объяснения потоков данных, взаимодействия между компонентами, API и модулями. Каждый фрагмент кода может иметь связанную документацию, к которой можно перейти одним щелчком мыши, и наоборот, вся документация, которую вы создаете, всегда будет отражать текущее состояние кода. Эта двусторонняя связь невероятно эффективна.
  • Документация обновляется автоматически. Это серьезное улучшение по сравнению с обычным процессом документирования, потому что одна из худших частей документирования огромной кодовой базы, которая постоянно меняется, — проверка всех образцов кода на актуальность. С Swimm, который больше не является ручной работой, его функция автоматической синхронизации сделает это за вас автоматически.
  • Блокировка поставщика отсутствует. Хотя все это звучит как волшебство, документация Swimm состоит из простых файлов Markdown, которые находятся прямо внутри вашего репозитория. Если вы хотите взять свои документы и переместить их в другое место, вы можете скопировать и вставить свои файлы, и все готово!
  • Вы делаете все в среде IDE. Я уже упоминал об этом, но как написание документации, так и ее использование выполняются напрямую, не выходя из вашей IDE. Не нужно отходить от кода, это определенно улучшение производительности! На следующем снимке экрана показано, как документация интегрирована в код. Нажав на этот небольшой текстовый фрагмент, вы откроете полную документацию этого компонента на виде сбоку рядом с кодом (чтобы не потерять контекст).

  • Упрощенная регистрация разработчиков с помощью плейлистов. Плейлисты — отличная функция Swimm, которая позволяет вам составить список страниц вашей документации для чтения, которые имеют решающее значение для любого, кто присоединится к вашему проекту.
  • Slack, Compass и другие интеграции. С помощью этих интеграций вы можете еще больше улучшить работу с документацией, уведомляя вас о создании нового документа или интегрируясь со всеми основными IDE (такими как VSCode, PyCharm и другими).

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

👉 Узнайте больше о том, как исключить переключение контекста, а также создавать и редактировать документы рядом с вашим кодом с помощью подключаемого модуля Swimm IDE

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

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

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

Удачного документирования!