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

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

Зачем нам нужны документы?

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

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

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

Подумайте, для кого вы это делаете

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

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

Где это написать?

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

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

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

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

Что мы сделали?

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

В основной файл README.md, помимо названия приложения, мы решили включить только ссылки на более конкретные подстраницы. Мы разделили документацию на следующие основные разделы:

  • Приступая к работе. Здесь мы описываем проект с точки зрения бизнеса, включая его цели, задачи и целевую аудиторию. Мы предоставляем информацию о доступных средах, URL-адресах и способах входа в приложение.
  • Разработка. В этом разделе рассматриваются требования к оборудованию и программному обеспечению, способы запуска проекта и основные задействованные сценарии. Мы также обсуждаем наш подход к тестированию компонентов и кода. Кроме того, мы включаем подраздел «Документация», в котором указано, когда следует обновлять документы и какую информацию следует включать. Цитирую из документации:

Проектная документация должна быть динамичным и постоянно развивающимся ресурсом. Его следует постоянно обновлять и пересматривать, чтобы отражать любые вносимые изменения или новые конвенции. Размышляя о том, стоит ли добавлять что-то в нашу документацию на GitHub, мы должны спросить себя: «Должно ли это быть включено?»

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

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

  • Запросы на включение. Мы определяем соглашение об именах ветвей, соглашение о сообщении о фиксации и требования, которым должен соответствовать запрос на включение для объединения. Мы также упоминаем о включении шаблона запроса на включение GitHub, который полезно иметь в репозитории, поскольку он позволяет автоматически создавать запросы на включение.
  • Выпуски. В этом разделе описывается, как выпускается продукт, включая частоту и конкретные шаги, необходимые для выпуска новой функции.
  • Потоки. В этом разделе мы стремимся объяснить более сложные темы, которые требуют подробных объяснений, помимо тех, которые могут быть предоставлены в комментариях к коду. В нашем случае это включает в себя такие темы, как аутентификация, рабочий процесс GraphQL и тестирование функций CORS.
  • Решения. Сюда мы включаем все технические решения, непосредственно относящиеся к проекту. Это служит нашей точкой отсчета в случае каких-либо сомнений. Оно действует как наш источник истины. Если существовал документ технического проекта (TDD), в котором мы рассматривали альтернативные варианты, мы включаем ссылку на этот документ.

Протестируйте, прежде чем объявить об окончании работы

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

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

Процесс, который никогда не заканчивается

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

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

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

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

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

Выводы

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

  • Документация необходима для эффективной передачи знаний: Независимо от того, знакомите ли вы нового члена команды с проектом или передаете его другой команде, хорошо документированный код и четкие инструкции делают процесс адаптации более плавным и минимизируют риски. неправильного толкования.
  • Документация повышает масштабируемость и удобство обслуживания проекта.Когда мы сталкиваемся с необходимостью внесения существенных изменений или обновлений в проект, комплексная документация позволяет нам понять тонкости системы и принять обоснованные решения. Это позволяет нам оценить потенциальное воздействие на различные компоненты и внести соответствующие коррективы.
  • Считайте документацию ценным продуктом.Отношение к документации как к продукту означает понимание ее ценности для аудитории. Создавая профили пользователей, мы можем лучше определить потребности и ожидания наших читателей, что позволяет нам адаптировать документацию к их требованиям.
  • Выберите правильное местоположение и формат.В зависимости от характера документации и ее целевой аудитории мы должны выбрать подходящее местоположение и формат. Уценка — это универсальный вариант технической документации, позволяющий включать фрагменты кода, изображения и параметры форматирования.
  • Регулярно тестируйте и повторяйте действия. Очень важно проверять эффективность нашей документации. Привлекая кого-то из нашей целевой аудитории, мы можем оценить доступность и удобство использования документации. Их отзывы помогут нам определить области, требующие улучшения, и обеспечить соответствие документации потребностям наших пользователей.

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