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

Такие вопросы особенно остро возникают, когда в команду приходит новый разработчик. Формально его быстро вводят в курс дела: показывают репозитории, рассказывают про архитектуру, делятся ссылками на несколько документов. Но дальше начинается знакомая история – обсуждения на созвонах, длинные переписки и фразы вроде «здесь есть нюанс» или «это лучше пока не трогать».

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

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

Технические документы – это всё, что помогает понять продукт без гаданий: требования, техзадания, архитектурные заметки, инструкции по установке, описание интерфейсов, релиз-ноты (замечания по версиям).

Иногда это ещё и «обязательная программа»: например, для части проектов ориентируются на ГОСТ 19 – «Единая система программной документации» (ЕСПД). Есть и международные нормы, например ISO/IEC 26514 – про пользовательскую документацию.

Но честно: чаще всего команды страдают не от отсутствия документов. Документы есть. Просто они лежат как осенние листья после шторма: по почте, в гугл-документах, в папках на сервере, в личных заметках. В итоге документ превращается в слух: «кажется, где-то было описание…».

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

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

Что такое техническая документация и что она включает в себя

Если без официальных формулировок, техническая документация – это описание системы, которое отвечает на четыре вопроса:

1. Что делает продукт.

2. Как он устроен.

3. Как его поставить, запустить, обслуживать.

4. Что делать, когда всё пошло не так.

И да, это читают не только разработчики. У тестировщиков свои боли. У админов свои. У поддержки вообще отдельная планета: им важно не «красиво», а «быстро понять, куда копать».

Обычно документ выглядит примерно так:

• требования и техническое задание (что делаем и зачем)

• архитектурное описание (из чего собрано, где границы, какие зависимости)

• инструкции по установке и настройке

• описание интеграций и интерфейсов

• релиз-ноты (что изменили и где ждать сюрпризы)

Иногда перечень документов диктуют стандарты. Например, ГОСТ 19.101-2020 из серии ЕСПД задаёт базовый набор материалов: техническое задание, пояснительная записка, методики испытаний, инструкции по эксплуатации и другие документы.

Но цель всё равно одна: чтобы любой специалист мог открыть документ и быстро въехать. Без «мы потом объясним».

Отсюда и требование к языку: чем понятнее, тем лучше. Это же, кстати, транслируют и международные подходы вроде ISO/IEC 26514: пользовательская документация должна быть читаемой, а не похожей на диссертацию.

И ещё практический момент: если документы не живут в единой базе знаний, вы почти гарантированно получите пять версий одного файла и шесть мнений, какая «самая свежая».

Виды технической документации

Самое удобное деление – по аудитории.

Пользовательская документация

Это тексты для тех, кто работает с системой, но не разрабатывает её.

Тут важна простота. Руководство пользователя (User Guide), инструкции по установке, справка, Вопросы и Ответы. 

Технологическая документация

Это для разработчиков и инженеров. И вот здесь уже нормально говорить на «техническом».

Сюда обычно попадает:

• спецификации API (Application Programming Interface – интерфейс программирования приложений)

• инструкции по развёртыванию (deployment)

• схемы инфраструктуры

• договорённости по конфигурациям и комментарии к коду

Если коротко, документ отвечает на вопрос: «как это реально собрано и как это поддерживать».

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

Проектная документация

Её часто недооценивают, пока не станет поздно.

Это про решения: почему сделали именно так, какие варианты рассматривали, какие компромиссы приняли. Архитектурные схемы, UML-диаграммы (Unified Modeling Language – язык моделирования систем), описание алгоритмов, аналитические заметки, дорожные карты.

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

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

Ненормально – когда никто не знает, что обязательно, а что «по желанию».

Как составлять техническую документацию

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

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

Второй момент – аудитория. Один документ не должен пытаться понравиться всем.

• Пользовательскому тексту нужен спокойный язык, примеры, расшифровка терминов.

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

Третий момент – структура во имя навигации: оглавление, разделы, версия или дата обновления. Это банально, но именно это спасает от вопроса «а это актуально?».

Шаблоны очень помогают. Причём не идеальные корпоративные, а простые:

цель → контекст → требования/ограничения → решение → как проверяем → что изменили.

И да, журнал изменений (change log) полезен. Особенно когда начинается «а кто это поменял и почему».

Про согласование тоже лучше не усложнять. Часто хватает схемы: автор написал → коллеги посмотрели → ответственный утвердил (архитектор или руководитель).

Главное, чтобы это было привычным шагом, а не событием раз в полгода.

Если команда ведёт документацию рядом с кодом,  распределённая система контроля версий (Гит) отлично закрывает вопрос версионности. История правок прозрачная: кто, когда, что изменил. Плюс можно делать запрос на изменения (pull request) на документы и обсуждать их как код.

Дальше идут «гигиенические» правила: доступы (кто читает, кто правит), бэкапы (резервные копии), регулярная уборка устаревших статей. Многие команды делают короткие спринты перед релизами – это реально работает, потому что есть понятный повод.

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

Где писать техническую документацию

Инструмент выбирают не «самый модный», а тот, который подходит команде.

Есть четыре частых сценария.

1) Базы знаний и приложения для создания контента
Confluence, Teamly, Notion и другие. Плюсы: совместное редактирование, поиск, права доступа, версии. Минусы: обычно платно.

Confluence, например, хорошо дружит с Jira и GitHub и поддерживает шаблоны. Teamly даёт единое пространство для документов разработки, поиск и аналитику по базе.

2) Документация рядом с кодом (GitHub/GitLab)
Приложения для создания контента, документации как кода (docs-as-code). Очень удобно разработчикам: всё рядом: история изменений, интеграция с задачами.

Минус понятный: не всем комфортно работать с кодом, особенно специалистам без технических знаний.

3) Автогенерация
Системы Sphinx, Doxygen, MkDocs и похожие инструменты. Хорошо для API (Application Programming Interface – интерфейс программирования приложений) и библиотек: минимум ручной работы, максимум связки с кодом. Но требует настройки и дисциплины.

4) Сервисы Google Docs / Office 365
Подходит для быстрых стартов и небольших объёмов. Но когда документов становится много, структура и поиск начинают «плыть».

База знаний технической документации на платформе Teamly

Когда компания растёт, в какой-то момент она понимает простую вещь: хорошо бы иметь одно место, где всё это хранится.

Так появляется идея так называемой «единой точки правды» – пространства, где лежит вся техническая документация и где её можно быстро найти. По сути, речь о довольно практичной задаче: документы должны быть собраны в одном месте, доступ к ним – понятным, а нужная информация – находиться через поиск за пару секунд.

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

Во-первых, поиск. Чем больше документов, тем важнее быстро находить нужную статью по нескольким словам.

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

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

Ещё один важный момент – интеграции. В реальной работе база знаний не существует отдельно: её связывают с Jira или системами CI/CD (Continuous Integration / Continuous Delivery – непрерывная интеграция и доставка).

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

Все эти вещи в сумме определяют, будет ли база знаний реально использоваться в работе или останется просто ещё одним хранилищем документов.

Поэтому в компаниях обычно формируют два уровня документации:

• внутренний контур – для команды разработки и сотрудников компании

• публичный контур – для пользователей продукта

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

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

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

Ещё один важный момент – связи между документами. В Teamly статьи можно связывать друг с другом ссылками и формировать полноценную систему знаний.

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

Для команд разработки также важно, что база знаний может использоваться не только как хранилище, но и как рабочий инструмент. Например, в Teamly удобно:

• вести технические заметки по архитектуре

• хранить договорённости по стилю используемого кода и инфраструктуре

• фиксировать решения архитектурных комитетов

• описывать процедуры внедрения и эксплуатации системы

• документировать новые функции перед релизом

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

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

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

Используйте инструменты TEAMLY, чтобы управлять рабочими процессами

Записывайтесь на онлайн-презентацию! Продемонстрируем интерфейс и все возможности платформы

Получить демо