Документацию можно готовить где угодно и как угодно. Писать инструкции в многочисленных CCMS, публиковать сайты через генераторы наподобие Sphinx, применять сложные разметки вроде DITA, вести базы знаний в Confluence или вообще собирать файлы в Word. У каждого инструмента и подхода есть свои плюсы и минусы. Выбор зависит от множества факторов: сложности, требований к результату, потребителя контента, бюджета отдела, объема накопившегося легаси — да и просто моды в профессиональной среде.
Но что если посмотреть на вопрос с другой стороны? Что если выбирать и проектировать систему документирования исходя из того, сколько свободы предоставляется техническому писателю?
Давайте выкрутим регулятор свободы на максималку сначала в одну сторону, когда техпис не имеет абсолютно никаких рамок и ограничений, а затем в противоположную, когда он тотально несвободен. Какие преимущества будут у каждой из этих двух крайностей и какие выводы можно будет сделать по итогу такого мысленного эксперимента — об этом моя статья.
Остров свободных техписов
Для начала закинем условного технического писателя — назовем его Петей — в среду, в которой ему в профессиональном плане никто и ничто не связывает руки. И представим его обычный рабочий день на таком острове свободных техписов.
Утром Петя, выпив кофе, открывает редактор и начинает писать очередную инструкцию. Система никак не подсказывает, как должен выглядеть текст. Нет шаблонов, нет обязательной структуры, нет списка разрешенных элементов. Нужно описать сложную процедуру — значит будет сложная процедура.
Петя решает начать раздел со скриншота, затем добавить таблицу с параметрами, а уже после этого описать шаги настройки. Между шагами он вставляет небольшие пояснения, чтобы читатель не терялся. В какой‑то момент приходит идея выделять термины пунктирным подчеркиванием, чтобы при наведении появлялось определение. Он пробует — выглядит неплохо, значит пусть так и будет.
На острове свободы такие вещи решаются быстро. Если техпису кажется, что какой‑то прием делает текст понятнее, он просто берет и использует его. Никакого корпоративного гайда, на который нужно ориентироваться, не существует. Коллега‑редактор не уточнит, разрешен ли новый элемент в документации — он может только советовать исходя из собственных представлений о прекрасном и насмотренности. Или же редактора и вовсе нет как такового.
Иногда из таких экспериментов действительно рождаются удачные решения. Документация постепенно обрастает новыми форматами, визуальными приемами и способами объяснять сложные вещи. Или остается простой как репа: люди разные, а технические писатели — те же люди.
После обеда Петя заканчивает инструкцию и публикует документ. Никакого сложного процесса выпуска нет: открыл редактор, написал текст, нажал кнопку публикации. В лучшем случае коллега может написать письмо с парой замечаний, но чаще всего все ограничивается быстрым просмотром.
Работа в такой системе идет быстро. Техпис почти не отвлекается на согласования, автопроверки и формальные требования. Вся энергия уходит непосредственно на написание текста.
Но чем дальше, тем больше начинают проявляться особенности островной свободы.
Петя ищет в документации описание похожей процедуры, чтобы не писать все заново. Похожие инструкции действительно находятся — несколько штук, в разных разделах. Только написаны они тоже по‑разному. Где‑то флажки «устанавливают», где‑то «отмечают», где‑то вообще «нажимают». Шаги процедур выглядят по‑разному, таблицы оформлены в разных стилях, а примечания каждый автор выделяет по‑своему. На подобное лоскутное одеяло читатель смотрит с недоверием.
Формально никто не запрещает переиспользовать контент. Возможно, у программы для этого даже есть специальные функции. Но никто и ничто к переиспользованию не подталкивает. Поэтому одна и та же операция может быть описана в нескольких местах и каждый раз немного иначе. Однажды Петя предложил коллегам формулировку для часто встречающегося шага инструкции, но те посчитали свои варианты текста более удачными. В горизонтальной системе первых среди равных на инициативу часто смотрят косо.
Ближе к вечеру в службу поддержки приходит тикет: пользователь выполнил инструкцию из документации, но желаемого результата не получил. Оказывается, в одном из шагов описан устаревший параметр. Теперь нужно понять, как эта ошибка попала в новую версию. Кто редактировал раздел? Было ли ревью? Проверял ли его кто‑нибудь перед публикацией? Ответы приходится искать по письмам и старым комментариям в трекере. А их там может и не быть вовсе: согласовывали документ устно, встретившись лично в опенспейсе, а одобрение «на бумаге» не зафиксировали. Следы затерялись.
Такие ситуации на острове случаются не из‑за плохих техписов. Каждый из них может быть профессионалом своего дела. Только вот сама среда почти не подстраховывает авторов. А когда контента становится много, начинает работать простая статистика: даже внимательные люди иногда что‑то пропускают.
Перед уходом с работы свободный художник Петя закрывает редактор. За день он написал хороший раздел документа — быстро и почти без ограничений. Но если посмотреть на весь остров целиком, становится видно, что свобода имеет цену: документация постепенно теряет единообразие, переиспользование не работает, а процесс выпуска остается непрозрачным.
В капкане антиутопии
Теперь представим, что тот же самый Петя «уволился» с острова и перешел на работу в совершенно другую систему. На новом месте документация строится вокруг строгих правил, а свободы у автора примерно столько же, сколько у пассажира в самолете во время турбулентности.
Утром Петя, выпив привычный кофе, открывает редактор и создает новый документ. Вернее, не совсем новый: система сразу подставляет шаблон с заранее заданной структурой. В нем уже есть обязательные разделы, предписанные типы блоков и даже примерные формулировки для некоторых элементов.
Попробовать начать инструкцию с картинки, как на острове, не получится. Шаблон требует сначала краткое описание процедуры, затем список условий, и только потом шаги выполнения. Петя пытается выделить целый абзац полужирным, чтобы подчеркнуть важное предупреждение. Редактор подсвечивает ошибку: такой тип форматирования в этом блоке запрещен.
Система не убеждает автора аргументами. Она просто не даст сохранить изменения, пока структура топика не будет соответствовать схеме.
Петя довольно быстро принимает правила игры и начинает работать в соответствии с корпоративным гайдом. В конце концов, он прописан довольно подробно: от структуры разделов до того, как именно и что выделять в тексте абзаца. В некоторых местах гайд даже предлагает готовые шаблоны предложений.
После обеда Петя заканчивает текст и отправляет его на ревью. Документ проходит несколько кругов проверок.
Сначала автоматические валидаторы тестируют структуру и семантику: все ли блоки стоят на своих местах, нет ли запрещенных элементов, корректно ли оформлены ссылки и таблицы. Опциональным, но рекомендуемым шагом следует LLM‑помощник: он снимает часть нагрузки с редактора, предлагая Пете более удачные формулировки.
Затем текст читают люди. Напарник‑техпис проводит перекрестную вычитку, редактор словно под микроскопом проверяет стиль и орфографию, дотошный документационный архитектор смотрит, соответствуют ли новый раздел и отдельные его части внутренней идеологии хранения информации. Все замечания фиксируются прямо в системе. Каждое исправление оставляет след: кто внес правку, кто подтвердил ее, кто поставил финальное одобрение.
После вычитки документ отправляется на публикацию через пайплайн сборки — в который тоже заложены проверки. Если машина обнаружит, что что‑то не так, пайплайн просто остановится и не пропустит документацию дальше.
Петя уже набил шишек и знает: качество контента обеспечивается на нескольких уровнях, и любая самодеятельность с его стороны, любое отхождение от гайда наказуемо.
Ближе к вечеру документ наконец публикуется. Он выглядит почти так же, как десятки других инструкций в системе. Те же типы блоков, те же формулировки шагов, те же стили таблиц и примечаний.
Зато у такой системы есть важные преимущества. Любой новый раздел сразу вписывается в общую структуру документации. Переиспользование контента работает проще: элементы стандартизированы, поэтому их легко переносить из одного документа в другой. Терминология остается стабильной, а структура инструкций — предсказуемой.
Кроме того, здесь всегда можно понять, как документ оказался в продакшене. В системе сохраняется вся история: кто писал текст, кто проверял его, кто поставил финальное одобрение. Если в опубликованном разделе обнаружится ошибка, найти ответственного обычно не составляет труда.
Но на одном только контроле такая система долго бы не прожила, поэтому рядом с кнутом всегда лежит и пряник. Каждая проверка, замечание ревьюера и ошибка, найденная автопроверками, фиксируются в системе. Чем меньше правок требуется документу, тем лучше это отражается на показателях автора. К концу квартала из этих данных вездесущий ИИ собирает отчеты по каждому техническому писателю: сколько замечаний получали его тексты, сколько раз сборки падали на автопроверках, сколько правок приходилось вносить после ревью.
Менеджеры любят такие таблицы и диаграммы. По ним легко понять, кто из техписов стабильно выпускает тексты без лишних проблем. А тем, кто аккуратно следует гайду и проходит все проверки с минимальными потерями, в конце квартала полагается материальная благодарность.
Правда, у этой аккуратной системы есть и обратная сторона. Петя замечает, что со временем начинает писать почти одинаковые тексты. Любая попытка попробовать новый способ объяснить сложную вещь упирается в ограничения системы. Некоторые идеи приходится просто отбрасывать — не потому, что они плохие, а потому, что система не предусматривает для них подходящего блока. Справедливости ради, внедрить идею можно, но это долгий и дорогой процесс с привлечением редакторов, документационных архитекторов и разработчиков справочного портала.
К концу дня Петя выпускает корректную, проверенную инструкцию. Она идеально соответствует гайду и проходит все тесты. Но иногда ему кажется, что он не столько пишет текст, сколько аккуратно заполняет заранее подготовленную форму. Петя устает от такой системы — ему кажется, что она душит его творческий потенциал. Быть может, думает Петя, нечто подобное подтолкнуло техписа Билла Кейсинга написать книгу о том, что американцы якобы не были на Луне.
Крутим регулятор контроля с умом
После двух таких крайностей возникает естественный вопрос: как вообще строить систему документирования?
Просто выбрать инструмент для написания документации, настроить процессы и написать гайд — недостаточно. Такая система может работать и даже со временем «притереться»: процессы устаканятся, команда привыкнет, мелкие проблемы сгладятся. Но архитектурные ограничения, заложенные в самом начале без учета уровня контроля, рано или поздно могут дать о себе знать. И тогда перестройка системы документирования превратится в дорогостоящий и болезненный проект.
Поэтому к построению такой системы разумнее подходить как к полноценной инженерной задаче: учитывать бюджет и возможности компании, цели документации, аудиторию контента, масштаб продукта и команды. Полностью просчитать все заранее может показаться утопичным, но стремиться к осмысленному проектированию системы все же стоит.
Прочитав обе истории‑крайности, вы могли бы подумать о золотой середине и о том, что хорошая документационная система лежит где‑то между тотальным контролем и абсолютной свободой. Но так работает не всегда.
Универсального баланса в принципе не существует: степень свободы всегда зависит от контекста. Например, в компаниях с госрегулированием и сферах, где ошибка в инструкции может стоить пользователю здоровья или жизни, ползунок неизбежно смещается в сторону жестких правил и проверок. В небольших стартапах с одним‑двумя продуктами ситуация обратная: объем документации относительно небольшой, сложные системы переиспользования не требуются, и у авторов может быть гораздо больше свободы.
Важно другое: любое ограничение свободы должно работать на конкретную цель.
История Пети на острове показывает, что абсолютная свобода плохо масштабируется. Когда каждый автор оформляет текст так, как считает нужным, страдает унификация, усложняется переиспользование контента и постепенно размывается структура всей документации. Чтобы этого не происходило, появляются шаблоны, типизация контента, информационная классификация, единые правила структуры — а вместе с ними и контроль. Иначе кто все это добро будет соблюдать?
Но и обратная крайность не работает. Если система начинает регулировать каждый чих, она превращается в тоталитарную машину, которая тратит больше сил на поддержание правил, чем на создание полезного контента. Тогда как не всякое ограничение оправдано. Если, например, нейминг сниппетов только удовлетворяет эстетические потребности архитектора и никак не помогает техписам находить нужные фрагменты, плохой идеей будет заставлять людей тратить время на придумывание названий.
Спускаем технооптимиста с небес на землю
Хорошо, мы подкрутили регулятор контроля, спроектировали систему. Но никакая система сама по себе не создаст качественную документацию — последнее слово всегда останется за людьми. Давайте рассмотрим три аспекта, где воодушевление технологией сталкивается с ограничениями свободы техписа.
Корпоративный гайд. Когда настольная книга техписа и редактора начинает диктовать, как жить, она легко скатывается из удобного руководства в уголовный кодекс. Но слово guide означает «направлять», а не «наказывать». Хороший гайд не ограничивает писателя ради самого ограничения, а помогает ему принимать решения. Иногда здравый смысл подсказывает, что в конкретном тексте уместна формулировка, формально противоречащая гайду. В зрелой системе такие случаи не считаются нарушением дисциплины — напротив, они становятся поводом пересмотреть сам гайд. Гайд остается живым организмом: он меняется вместе с практикой работы команды и адаптируется к новым вызовам.
Искусственный интеллект. ИИ может помогать авторам, редакторам и менеджерам: искать ошибки, анализировать тексты, генерировать отчеты. Но пока рано превращать ИИ в таможенника, не пропускающего справочный контент к читателю. Системы, склонные к галлюцинациям, не подходят для того, чтобы по их вердиктам блокировать релизы. Гайд задает рамки, ИИ помогает их соблюдать, но человек всегда остается главным в принятии решений.
Ответственность автора. Чем больше система принимает решений за технического писателя, тем меньше ответственности остается у него самого. Со временем работа строго по шаблону притупляет инициативу и мешает профессиональному росту. Поэтому если система сильно ограничивает писателя в одной области, имеет смысл дать ему больше ответственности в другой. Вовлекать технических писателей в разработку гайдов, процессов и промптов для LLM — важная часть этого подхода. Редактор, пишущий гайд, — само собой. Но не менее важно участие тех, кто ежедневно создает тексты и хорошо понимает, как правила работают на практике.
Что в итоге
Истории про техписа Петю показывают: ни абсолютная свобода, ни тотальный контроль не работают сами по себе. Любая система документирования — это набор компромиссов: одни ограничения помогают масштабировать контент, другие создают лишнюю бюрократию.
Даже самые продуманные правила и инструменты ничего не стоят без людей, которые ими пользуются. Иногда технологии вдохновляют на идеи, как у технооптимиста, иногда ограничения свободы заставляют искать обходные пути — но именно эти решения и делают документацию полезной.
Задача команды — не зафиксировать регулятор навсегда, а подстраивать его под реальные потребности. Тогда и Петя сможет работать продуктивно, и система останется живой и гибкой.
Автор: Cuder
