Подготовка технической документации *

Привет, Хабр! Меня зовут Алиса Комиссарова, я руководитель отдела автоматизации и поддержки документирования Positive Technologies.

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

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

“User — это не he. User - это they. Аккуратно с этим в международных командах”.

На днях из-за этой короткой заметки в моих соц. сетях разразился настоящий скандал.

Возмущались в основном мужчины. Даже вялый прежде LinkedIn бушевал все майские.

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

Привет, Хабр! Меня зовут Николай Чурянин, я занимаюсь iOS-разработкой в ПСБ. Сегодня я хочу рассказать вам, как делал новую документацию для нашего модуля CI/CD. Конечно же, документация у нас была и раньше. И даже не одна — а это, как понимаете, только усугубляло проблему. Часть документации лежала в readme-репозитории — с него-то она по сути и началась. Но обновлялась она там нерегулярно, оказалось, что работать с ней было не очень-то удобно. В какой-то момент этот репозиторий перестали поддерживать, и я попытался оформить её на внутреннем портале. Увы, пользы от этого стало ещё меньше: там документация была оторвана от кода — от наших скриптов. Вдобавок, её было трудно обновлять. Надо ли говорить, что и её забросили?

«Совсем без документации тоже нельзя», —  решил я и принялся искать другой способ. И нашёл его (спойлер: без ИИ тут не обошлось). Покажу, что получилось и как всё теперь работает. 

Представьте: ваш первый день в офисе, вам дали доступы ко всем 15 репозиториям проекта, рассказали где что лежит, и теперь ждут от вас великих дел. Тем временем вы едва можете вспомнить, какой карточкой открывается этаж и где стоит кофемашина.

Добро пожаловать в 50% IT-компаний во вторую статью цикла про онбординг в сложную систему!

В этой статье превратим плоский список репозиториев в рабочую onboarding-map: сначала определить роли, потом соберем dependency matrix, а затем получим relationship diagram.

Привет, Хабр! Меня зовут Артём Зеленкин, приятно познакомиться! Я работаю техническим писателем около 20 лет, сейчас занимаюсь документированием в подразделении ARMA компании Infowatch. Для создания и поддержки актуальности документации по продуктам линейки ARMA мы используем docs-as-code. Что из этого получается, можно посмотреть на сайте с документацией (там же можно скачать pdf-версию, чтобы сравнить, как оно выглядит в разных форматах при тех же исходных данных).

В данной статье я не пытаюсь рассказать, что такое docs-as-code (думаю, статей по теме достаточно), а рассказываю, как этот принцип реализован у нас. Может, вам тоже пригодится.

wkhtmltopdf долгое время был одним из основных инструментов для генерации PDF из HTML. Мы столкнулись с ним на собственном проекте, но, когда потребовалось реализовать сложные макеты, колонтитулы и повторяющиеся заголовки в многостраничных документах — возникли проблемы.

В этой статье — краткий обзор альтернатив (Headless Chrome, Puppeteer, Playwright, WeasyPrint, Gotenberg), их плюсы и минусы, а также наш итоговый выбор и подводные камни, которые всплыли в процессе внедрения.

Вы прочитали гайд по Cursor, посмотрели демку Claude Code, посчитали в голове экономику и решили: пора. Спускаете в команду указание — попробовать на следующей итерации. Через две недели смотрите на цифры и видите, что lead time не сократился, а вырос. Полетели странные инциденты в трекер. Двое лучших разработчиков ходят с лицами «я же говорил». На ретро звучит сдержанное «нам нужно больше времени, чтобы оценить эффект». На самом деле это значит «уберите эту штуку».

Знакомо? Это типичная картина внедрения ИИ в инженерной команде через администрирование. Проблема не в инструменте, не в моделях и не в скептиках. Проблема в том, что push‑модель (принуждение) внедрения системно не работает с разработчиками высоких грейдов — и чем сильнее ваша команда, тем хуже она работает.

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

Привет, Хабр! Последние полгода стало модно создавать новые и переводить старые проекты на рельсы AI-First (или AI-Friendly) стандарта. Уже появляются проекты, которые декларируются как «designed for AI to write». Например, AIR — AI-First веб-фреймворк на Python.

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

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

Уважаемый читатель, хочу продолжить тему десятипальцевой печати, которая была начата в статье "Десятипальцевый метод печати в ВУЗе" https://habr.com/ru/articles/1024642/

Уже несколько лет я преподаю информатику студентам из Индии, занятия веду на английском языке. И вдруг от университета поступило предложение - дополнительно взять франкоговорящую группу из Марокко.

Свой французский я ранее рассматривал как хобби, а тут появилась возможность практического применения! Я согласился и стал готовиться. Во-первых, надо было официально подтвердить знание языка. Обратился на кафедру романо-германской филологии, прошел курс "Французский язык для преподавателей", сдал экзамен.

Следующий этап - подготовка материалов для преподавания. Я воспользовался гугл-переводчиком и перевел курс информатики с английского на французский. Попросил товарища, носителя языка, подкорректировать текст.

У моего курса есть одна особеность. Одновременно с изучением информатики, студенты изучают 10-пальцевый метод работы на клавиатуре.

В разных франкоговорящих странах используют разные раскладки. Какую раскладку взять для Марокко? Уточнил, что там используют раскладку как во Франции. С помощью программы Paint переделал рисунок английской клавиатуры из своего курса на французский лад. Зоны для пальцев оставил такие же ( см.рисунок).

Для контроля освоения клавиатуры нужна фраза, в которой содержатся все буквы алфавита. Англоговорящие у меня печатают: Quick brown fox jumps over the lazy dog

А что можно предложить франкоговорящим? Перебрал несколько вариантов, остановился на таком: Mixez goyave, pêche, kiwi, quel bon jus de fruit !

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

И вот, в текущем учебном году, дополнительно к группам из Индии я провел курс для группы из Марокко.

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

После 12 занятий большинство студентов сдали тест “слепой печати”.

Тест достаточно сложный - студент печатает тестовую фразу, и при этом не видит клавиатуру и экран, они закрыты ширмой.

Затем, после сдачи теста, был проведен конкурс на скорость. Наибольшая скорость печати у франкофонов составила 193 символа в минуту.

Для сравнения, наилучшая скорость печати у англоговорящих составила 201 символ в минуту.

Несмотря на неплохие показатели, я не считаю скорость важным критерием. Быстро печатать можно и двумя пальцами. А вот то, что они печатали десятью пальцами “вслепую” - это хорошее достижение.

Обучающие файлы Excel для франкофонов, с рисунком клавиатуры, диакритическими знаками, измерителем скорости печати, можно скачать по ссылкам __

Буду рад услышать отзывы о моей методике, отвечу на вопросы.

Итак, вы нашли своего идеального кандидата. Возможно, он даже очень силён, но спустя 2 месяца всё ещё не вышел на ожидаемую продуктивность. Более того, вы заметили, что производительность команды только снизилась, потому что другие инженеры тратят время на онбординг нового человека.

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

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

Почему?

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

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

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

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

Любой более-менее живой репозиторий уже давно перестал быть просто директорией с исходным кодом. Помимо файлов с исходниками там теперь живут инструкции, архитектурные заметки, спецификации, техническая документация и отчёты, которые должны одинаково хорошо читаться и в IDE, и в веб-интерфейсе платформы. Даже сейчас в процессе написания этой статьи я использую Markdown-разметку, которая стала де-факто стандартом для ведения документации в проектах, но давайте обо всем по порядку.

Когда таких форматов становится много, возникает закономерный вопрос: как показать их пользователю удобно, быстро и без необходимости скачивать файл к себе на компьютер? У нас в GitVerse этот вопрос постепенно вырос в отдельную продуктовую и инженерную задачу. Так появилась поддержка просмотра разных типов файлов — от упомянутого выше Markdown до более специализированных форматов.

Я расскажу, почему вообще человечество пришло к идее текстовых форматов для оформления документов, как Markdown стал фактическим стандартом индустрии, зачем нужен Typst и как мы внедряли его поддержку на платформе с помощью WebAssembly.

Сколько людей - столько и мнений о процессах в команде (с). 

Давайте поразмышляем - как выстроить процесс анализа так, чтобы он стал для команды не формальным набором этапов, а рабочим инструментом? Опираемся на наш опыт работы в командах разработки одного из операторов электронного документооборота.  Все описанные процессы формировались и развивались на практике.

За отправную точку возьмем несколько потребностей: 

• управлять неопределённостью,

• повышать качество требований,

• снижать риски на этапе разработки. 

Поделимся опытом работы в команде разработки продукта электронного документооборота. 

Расскажем о своих решениях, ошибках, находках, и компромиссах и о рабочей модели, которой мы сейчас придерживаемся.

Каждый день через системы «Честного знака» проходят тысячи страниц: контракты, акты, техдокументация, анкеты. Всё это нужно не просто перевести в текст — а сразу пустить в работу: поиск, анализ, генерация выжимок, передача в другие сервисы. Одна ошибка OCR — и вместо «субподрядчика» система получает «cy6пoдpялчика», а дальше никакие регулярки не спасут.

Меня зовут Искандер, я - AI-инженер в Лаборатории искусственного интеллекта «Честного знака». Мы протестировали лучшие open-source OCR-движки на реальных русскоязычных документах — от простых текстов до многостраничных PDF со сложными таблицами и изображениями. Специфика задачи: кириллица, широкий разброс форматов, нулевая терпимость к ошибкам на продакшне.

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

Привет, Хабр и коллеги-техписы! Я Оля Исхакова, работаю техническим писателем в Т-Банке. Мы с командой занимаемся развитием документации для внутренних продуктов, пишем коммуникации, анализируем пользовательский путь и предлагаем идеи по улучшению интерфейсов. 

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

В рамках данной статьи рассказываю об очередных нововведениях в законодательстве о персональных данных.

С 30 мая 2025 вступил в силу Федеральный закон от 30.11.2024 № 420-ФЗ «О внесении изменений в КоАП РФ», пунктом 10 которого установлена ответственность за невыполнение или несвоевременное выполнение оператором персональных данных обязанности по уведомлению уполномоченного органа по защите прав субъектов персональных данных о намерении осуществлять обработку персональных данных.

А теперь перевожу с юридического на человеческий все важные нюансы указанного нововведения ↓

Уважаемый читатель, хочу поделиться опытом преподавания 10-пальцевой печати в ВУЗе.

Сначала расскажу, как я к этому пришёл. Семь лет назад меня попросили вести уроки информатики у студентов-медиков. Я начал работать и увидел, что интерес к предмету очень слабый. Задумался, как сделать занятия увлекательными и полезными. И решил совместить изучение предмета с изучением клавиатуры.

Идея простая — давать студентам небольшие тексты по теме урока, чтобы они их перепечатывали. Но как добиться именно 10-пальцевой печати?

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

Чтобы упростить процесс, я решил перенести карточку на экран. Как? Очень просто. Открыл файл Excel, расширил верхнюю строчку и вставил туда рисунок клавиатуры. А строчку «заморозил». Теперь ниже можно печатать сколько угодно текста, рисунок-подсказка всегда стоит перед глазами.

Уточню насчет рисунка. При распределении зон для пальцев существуют разные варианты. Я использовал вариант, который предлагает Министерство образования в учебнике информатики за 7 класс, автор Босова Л.Л. Но одного рисунка с клавиатурой мало. Надо ещё отработать движение рук.

Привет Хабр! В нашем блоге кейс-пополнение. Дисклеймер: По причине соглашений о неразглашении (NDA) мы не всегда можем указать на конкретного заказчика, но стараемся описывать задачу проекта и ее решение максимально подробно. Сегодня рассказ про применение ИИ в российской металлургии. Итак, после предисловия перейдем к теме статьи.

Давным-давно, кажется в позапрошлый вторник,  в одной из статей была поднята тема зарабатывания денег, где я поделился личным опытом работы на программных проектах, на рентабельность которых существенно повлияла проектная и эксплуатационная документация. По аналогии с фильмом "MoneyBall" материалы этой серии я объединил под названием "MoneyDev".

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

Привет! Я Оля Коршунова, лид первой редакции технических писателей в Т-Банке. Боль технических писателей — как определить влияние текста? Как оцифровать его в бизнес-результат?

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

В статье расскажу, с чего команда начинала работу и как пришла к метрикам документации.