2 вида технической документации, которые нравятся разработчикам

documentation

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


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


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

API-контракты


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


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


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


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


Но насколько отличается процесс, когда продукт не является техническим инструментом для других — например, когда команда строит приложение для заказа такси? Не существует публичных классов или API, которыми можно было бы поделиться с остальным миром, так имеет ли смысл все документировать?


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


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


Код и API в таких продуктах постоянно меняются по мере адаптации продукта к потребностям рынка. Например, зачем писать документацию к классу, который становится наследственным уже через 6 месяцев? Хотя это верно для классов, на самом деле это не применимо к REST API, так как оно обычно живет дольше. Даже когда все это понятно для команды, в течение года новые участники будут спрашивать, как работают определенные конечные точки и какой формат ответа.
К сожалению, не все способны ответить на этот вопрос. Документирование этих деталей поможет распространить знания за пределами команды. Это инвестиции для всей компании, которые напомнят команде, как работает API, помогут другим командам внести свой вклад в эту область и помогут новичкам быстрее наверстать упущенное.

Подходы и потоки

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

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


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


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


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

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


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

About the Author: Lazizbek Ergashev

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *