Documentation as code: практики и инструменты документирования в сфере финансовых технологий

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

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

1. Эволюция документации

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

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

2. Основы Documentation as code

Documentation as code – это подход к разработке технической документации цифрового продукта, который подразумевает хранение требований, архитектурных решений и пользовательских инструкций в виде простых текстовых файлов. При этом, документация пишется на языках разметки, таких как MarkDown, хранится в репозитории Git и может обновляться и развиваться вместе с проектом.

Вот несколько ключевых принципов Documentation as code:

1. Написание документов следует принципам написания кода, целью которых является создание четкой структуры для легкого понимания и чтения. К ним относятся:
2. DRY (Don’t Repeat Yourself): Важно избегать дублирования информации в документах.
3. KISS (Keep It Simple, Stupid): Необходимо избегать ненужной сложности и стремиться к простоте изложения информации.
4. YAGNI (You Aren’t Gonna Need It): Добавлять новый функционал нужно только тогда, когда он становится абсолютно необходимым, чтобы избежать лишней работы.
5. SRP (Single Responsibility Principle): Каждый блок документации должен быть ответственным только за одну часть функциональности для сохранения четкости. структуры.
6. SLAP (Single Level of Abstraction Principle): Необходимо разбивать большие документы на уровни абстракции и делать для каждого уровня отдельные лаконичные документы. 
7. LoD (Law of Demeter): Необходимо делать ссылки только на релевантные документы.
8. Современная документация ориентирована на пользователя, в ней ценятся не только читаемость, но и визуальная составляющая. Поэтому использование визуальных средств, таких как диаграммы, графики и видеоруководства, также становятся все более важными.
9. Документация предполагает единый стиль кодирования, включая структуру текста, отступы, пробелы и т.д. для облегчения понимания.
10. Использование специализированных инструментов для создания, совместного использования и обновления документации. К ним относятся Confluence, ReadTheDocs, Swagger (для API) и другие.
11. Встраивание документацию непосредственно в код, для упрощения ее поддержки и обновления.
12. Отслеживание изменений, обновлений и исправлений в документах при помощи Changelog для понимания эволюции проекта.

В отличие от традиционных подходов, documentation as code отдает приоритет версионирования, модульности и автоматизации, что делает ее более гибкой и адаптивной к изменениям. В то время, как ранее документация готовилась в самом начале проекта и практически не менялась, с появлением Agile методологий Scrum и Kanban фокус сместился на ее итеративное обновление, при котором она эволюционирует вместе с проектом.

3. Преимущества использования ASCII doc и Plantuml

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

Ниже его главные преимущества:

1. Простота: ASCII doc использует легко читаемый синтаксис, упрощая написание и редактирование технических документов.
2. Универсальность: Документы ASCII doc легко преобразуются в различные форматы, включая HTML, PDF, ePub, обеспечивая гибкость в представлении и распространении документации.
3. Версионирование и совместный доступ: Благодаря текстовому формату, ASCII doc легко интегрируется с системами контроля версий, упрощая совместную работу и мониторинг изменений в документации.
4. Автоматизация: ASCII doc поддерживает автоматическую генерацию документации из исходного кода, сокращая время и усилия для поддержания актуальности технических документов.
5. Масштабируемость: ASCII doc позволяет управлять сложными документами с множеством разделов и подразделов. Это делает его удобным для сектора финансовых технологий, где доминируют большие проекты с комплексной документацией.
6. Совместимость с инструментами CI/CD: ASCII doc легко интегрируется в практики непрерывной интеграции и непрерывной доставки (CI/CD), которые часто используются в fintech-проектах.
7. Безопасность: ASCII doc помогает создавать подробную и постоянно обновляющуюся документацию, что критически важно в fintech, где строгие стандарты безопасности и регуляторные требования постоянно обновляются.

PlantUML — это инструмент для быстрой генерации сложных диаграмм из текстового описания. Он особенно популярен для создания различных видов диаграмм, включая диаграммы UML (Unified Modeling Language), диаграммы последовательностей, случаев использования, классов, активностей, компонентов и состояний.

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

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

4. Кейс: Documentation as code на практике

Strands, FinTech компания, которая специализируется на разработке высокотехнологичных персонализированные решения для управления цифровыми деньгами, успешно использует подход documentation as code.

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

5. Преодоление вызовов и ограничений

Ключевыми проблемами при внедрении концепции documentation as code обычно становятся необходимость изменения устоявшихся подходов к документированию и разработке, a также адаптация к новым инструментам и процессам​​​​.

Для решения этих проблем, необходимо включить технических райтеров в команду разработки, обеспечить использование легких в освоении инструментов разметки, таких как ASCII doc и Plantuml, и применять системы контроля версий, например Git, для улучшения версионности и совместной работы​​​​​​.

6. Будущее документации в Fintech

Развитие технологий не стоит на месте, стимулируя трансформацию подхода documentation as code. Представим несколько ключевых трендов развития документооборота в сфере финансовых технологий:

1. Разработка программного обеспечения с повышенным уровнем защиты от кибератак.
2. Использование облачных технологий для улучшения совместной работы и доступности данных.
3. Внедрение AI технологий для автоматизации повторяющихся задач.
4. Автоматическая сортировка и архивирование документов.
5. Разработка планов для поддержания стабильности бизнес-процессов.

Заключение

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