 |
|
|
|
Ох, уж эта документация!
Ох, уж эта документация!Документацию все признают важной, хотя ее мало кто любит делать. Зачастую она либо отсутствует, либо устарела, либо написана так, что читать её невозможно. Но документация спасает в критический момент — при инциденте, при передаче смены или уходе коллеги. Как же вести ее правильно? 1. Какая документация в вашей команде действительно работает, а какая существует «для галочки»? Приведите пример. На вопросы отвечают эксперты компаний
«С устареванием документации мы боремся механизмом, а не энтузиазмом: энтузиазм заканчивается на третьем документе»1. Работает та документация, у которой есть читатель кроме автора. Проверка грубая: открывал ли документ кто-нибудь после сдачи. В нашей практике таких документов три. Программа и методика испытаний — ее смотрят обязательно, потому что по ней принимают систему. Руководство пользователя — его всегда просят, когда появляется новый функционал. Пояснительная записка к техническому проекту — ее чаще всего использует технический заказчик. Остальное пишется как сопроводительный текст к факту и после сдачи не открывается. Если документ не читают, он либо не нужен, либо нужен в другом виде: таблицей или записью в системе. 2. Прием, который снимает мучения при ведении документации. Один и главный: развести в документе постоянную часть и переменную. Все, что меняется — наименования, адреса, версии, состав, ответственные, — вынести из текста в отдельный источник и подставлять по ссылке. Текст остается шаблоном. Выгода видна на первом же изменении. Заказчик попросил поменять регистрационный номер системы. Раньше это означало правку колонтитулов и титульных листов во всех документах комплекта. После перехода на подстановку — изменение одного значения, и весь комплект обновился. 3. Когда документация подвела. Самое сложное в документации — успевать актуализироваться вместе с кодом. Скорость разработки выросла кратно, и описание почти всегда отстает: функционал уже изменился, а в документе он прежний. Типичный пример — настройки ролевой модели: права перенастроены, добавились новые роли, а руководство описывает прежнюю схему. Катастрофы в моменте нет, но отсюда ошибки при настройке и вопросы в поддержку. 4. Как мы боремся с устареванием? Механизмом, а не энтузиазмом: энтузиазм заканчивается на третьем документе. Механизм один: единый источник. Если сведения лежат в одном месте, а документы собираются из них, то устаревать нечему — устаревают только копии. Проблема обновления существует ровно до тех пор, пока одно и то же записано в пяти файлах. Второй слой — автоматическая проверка оформления и состава. 5. Когда писать надо, а времени нет. Тогда — минимально достаточное, то, что нельзя восстановить, глядя на саму систему. Конфигурация, состав компонентов и версии видны и без документа. А почему выбрано именно это решение и что сломается при изменении — этого в системе нет, и оно уйдет вместе с человеком. Поэтому сначала пишем переменные: реквизиты, состав, связи, ответственных. Это скелет, на который текст нарастает потом. Обратный порядок не работает: текст придется переписывать после каждого уточнения. Отдельно про ИИ-агента: если шаблоны заранее размечены, комплект собирается за день — данные подставляются, текст достраивается по разделам. И условие, о котором легко забыть в спешке: модель работает с реальными данными проекта, поэтому контур безопасности и требования 152-ФЗ нужно решить заранее.
«Хорошая документация экономит время всей команды, упрощает передачу задач и помогает поддерживать стабильность работы даже тогда, когда нужного специалиста нет на месте»Для меня документация — это прежде всего рабочий инструмент, который помогает решать повседневные задачи. Например, у нас хорошо работает документация по обработке заявок на предоставление различных доступов. В ней описан порядок действий, что позволяет выполнять такие запросы последовательно, не упускать важные шаги и придерживаться единых правил. Это важно, когда с одной задачей могут работать разные специалисты: результат не должен зависеть исключительно от личного опыта конкретного сотрудника. В качестве основного инструмента для ведения документации мы используем Confluence. Но, на мой взгляд, дело не столько в выбранной системе, сколько в привычке команды работать с накопленными знаниями. У нас есть простой принцип: если специалист изучил что-то новое, разобрался в нестандартной ситуации или уточнил порядок выполнения какой-либо операции, он должен внести соответствующие изменения в статью. Это позволяет постепенно превращать индивидуальный опыт сотрудников в общее знание команды. У нас не было случаев, когда отсутствие документации приводило бы к серьёзному сбою, однако на практике проявлялись другие последствия. Например, во время моего отпуска возникла ситуация, когда коллеге потребовалось выполнить задачу, порядок решения которой не был описан в отдельной статье. В результате ему пришлось разбираться самостоятельно, поскольку готовой инструкции не оказалось. Это не привело к инциденту, но показало, насколько отсутствие документации может усложнить работу и создать зависимость от конкретного специалиста. Системный администратор может помнить множество нюансов, но рассчитывать на то, что коллеги всегда смогут оперативно получить эти знания лично у него, неправильно. Поэтому к актуальности документации мы стараемся относиться как к части обычной работы. Если в процессе изменений меняется порядок действий, настройки или используемые инструменты, информация обновляется сразу. Кроме того, когда мы обращаемся к существующей статье и замечаем, что данные устарели или не соответствуют действительности, мы вносим необходимые корректировки. Отдельного сложного механизма, который принудительно заставлял бы сотрудников обновлять каждую статью, у нас нет: многое строится на принятом в команде подходе. Я считаю, что документация начинает действительно работать тогда, когда её воспринимают не как дополнительную нагрузку, а как естественную часть решения задачи. Необязательно описывать абсолютно всё с одинаковой степенью подробности. В первую очередь стоит фиксировать процессы, которые повторяются, требуют соблюдения определённой последовательности действий или зависят от знаний конкретного сотрудника. В конечном счёте хорошая документация экономит время всей команды, упрощает передачу задач и помогает поддерживать стабильность работы даже тогда, когда нужного специалиста нет на месте.
«Идеальная документация — враг существующей. Лучше три строки сейчас, чем десять страниц никогда»1. Работает то, что привязано к коду. В MyTona мы документировали ETL-пайплайны прямо в DAG-файлах Airflow: источник, частота, ответственный. Открываешь DAG — сразу видишь суть. 2. Три приёма. Один README на репозиторий — единственная точка входа. Автогенерация: скрипт вытягивает схемы BigQuery-таблиц и lineage в Markdown по расписанию Airflow. Шаблоны: в Softline Solutions каждый пайплайн стартует с cookiecutter-шаблона, где документация заполнена на 60%. 3. Сбой из-за отсутствия документации — в MyTona был Kafka-консьюмер игровых событий. Автор уволился, документации — ноль. Через три месяца консьюмер начал терять сообщения. Два дня разбирали чужой код. Потеряли данные за 14 часов. После этого — правило: пул-реквест без docstring и README получает автоматический реджект. 5. Приёмы «минимально достаточного» документирования. Правило трёх строк. Любой пайплайн: что делает, откуда данные, куда кладёт. 30 секунд работы. Нет и на это — TODO с датой и номером тикета. Идеальная документация — враг существующей. Лучше три строки сейчас, чем десять страниц никогда.
Подпишитесь на журнал |
Никита Осокин,
Максим Невмержицкий, 
Тимур Рахматуллин, Комментарии отсутствуют
| Добавить комментарий |
|
Комментарии могут оставлять только зарегистрированные пользователи |
|
