Всё о деятельности технических писателей
Токен — это единица текста.
AI-действие — это единица полезного результата.
AI-действия - это не абстракция и не побочный эффект автоматизации. Это измеримый экономический ресурс, который уже сегодня создаёт реальную ценность. Осталось лишь признать его в балансе.
Если вы хоть раз программировали контроллер на реальном объекте, вы знаете этот ритуал. Перед вами лежит PDF на 180 страниц — «Техническое задание на разработку АСУ ТП». Рядом — Excel с IOLIST на 600 строк. Ваша задача, прежде чем написать первую строчку кода на ST или LAD, — разобраться, что куда относится: какие сигналы принадлежат вентиляции, какие — насосной станции, что за уставки у каждого узла, где аварии, где режимы. Это занимает полдня в лучшем случае, день — в среднем.
Именно эту боль закрывает PLC Smart Splitter — новый инструмент от российской студии plcstudio, опубликованный в открытом доступе на GitVerse и GitHub.
Я техписатель, чьи тексты принимают за ИИ-шные. И вот что выяснилось…
Так случается: пишешь текст сам, вычитываешь, вычищаешь, убираешь воду – а потом коллега спрашивает: «Это ChatGPT?»
И снова привет, Хабр! Я Артем Клещев, технический писатель в СберТехе.
Недавно я рассказал, как построить удобную архитектуру репозитория продукта и вести единый источник в Docs-as-Code вместо разрозненных комплектов документации. Сегодня хочу поделиться тем, как мы добавили к такой архитектуре новый для нас, модифицированный процесс ведения Git — Feature Branch Workflow — и значительно сократили время подготовки документации.
Расскажу, как этот метод версионирования помог нам упростить и ускорить работу. Обсудим, как можно удобно работать в единой ветке и выпускать несколько хотфиксов документации за день.
Объяснять буду на примерах из документации продукта Platform V DropApp — решения СберТеха для управления контейнерными приложениями.
Договоры — головная боль всех, кто с ними сталкивался. Сначала все выглядит нормально: предмет, сроки, оплата, ответственность, реквизиты, подписи. А потом начинается: исполнитель понял объем работ иначе, заказчик задержал оплату, дедлайн оказался «примерным», правки бесконечные, результат приняли устно, а ответственность размазана так, что никто ничего никому не должен.
Нейросеть может помочь составить договор быстрее и безопаснее. Юридические организации все чаще признают пользу ИИ в правовой работе. ABA в чек-листе для юрлиц пишет, что нейросети используют для писем, резюме документов, правового анализа и анализа договоров, но разница между пользой и риском зависит от выбора инструмента, контроля и проверки результата.
Мы подготовили 5 промптов, которые помогут составить договор через нейросеть осознанно — рабочий документ под конкретную сделку.
Практически в каждой свой статье, в которой прямо или косвенно идёт речь о важности соблюдения Закона о персональных данных, я упоминаю риск получения административного штрафа по ст. 13.11 КоАП РФ. Теперь давайте поговорим не про «очередные страшилки для бизнеса», а про реальную судебную практику.
Существуют разные способы печати десятью пальцами, различаются манеры движения кистей рук, зоны ответственности пальцев.
Основная позиция ФЫВА — ОЛДЖ считается базовой во всех известных мне системах. Однако последующее движение рук и пальцев может значительно отличаться.
Привет, Хабр! Сегодня мы часто говорим про разные тренды в разработке — ИИ‑агентов, тестирование на ранних стадиях, прослеживаемость изменений, автоматизацию пайплайнов… Все эти тренды звучат убедительно, пока не упираются в реальность: требования лежат в на общих дисках, схемы — в картинках, контракты — в разных версиях, а история изменений размазана по инструментам.
Что делать с этим?
Лев Немировский, руководитель направления по развитию инструментов внедрения ПСБ, рассказал, чем полезен в этом случае подход GitOps и о том, как и в каких случаях это может упростить жизнь команде.
Некоторое время назад я обнаружил набор скриптов, помогающих собирать операционную систему GNU из исходников. К моему сожалению, в исходниках не содержалось указание на лицензию, под которой они распространяются. Я написал их автору, что отсутствие указания лицензии делает скрипты проприетарными, а это противоречит духу проекта GNU. Ответа я не получил…
Не опускайте лицензию и копирайт в своих исходных текстах, если, конечно, вы их кому-то предоставляете. Я регулярно заглядываю в открытые исходники и часто вижу, как их авторы допускают ошибки, касающиеся авторских прав и лицензирования. И хотя я не юрист, а лишь осведомлённый дилетант, позволю себе здесь рассказать о часто встречающихся проблемах с лицензиями на исходные тексты программ. Моя цель не руководство к действию дать, а поднять наболевшую проблему наверх. Это важно, если мы хотим оставаться в рамках закона и при этом быть защищены. Это нужно, чтобы открытые исходники и свободные программы не были лишь набором слов, а реальным инструментом в достижении наших целей.
Ещё двадцать лет назад понятия свободного программного обеспечения и открытых исходных текстов были неведомы чуть менее чем всем пользователям компьютеров, да что там говорить, самим программистам. Linux, BSD, OpenOffice, Gimp были диковинкой и вызывали удивление. Но Мир изменился. Опубликованным исходникам нет счёта, и мало кому из, по крайней мере, программистам, нужно объяснять, что это такое. Мир изменился, но люди нет. Невежество и чванство никуда не делись. Изучая чужие разработки в исходниках, не перестаю замечать, как много проектов игнорируют необходимость указания лицензии и копирайта.
Почему указание лицензии важно? Лицензия даём нам, как пользователям программ, так и программистам, изучающим чужие исходные тексты и использующим их в своих программах, чётко обозначенные права (разрешения) и ограничения (запреты). Отсутствие же лицензии означает одно: вам не предоставлено никаких прав, вообще.
Давайте разберём типовые ошибки авторов программ, и поджидающие их пользователей проблемы.
У нас было 120 процессов, 9 областей управления, более 100 авторов из 60 компаний, 3 ветки на каждый репозиторий и ещё по одной на каждую задачу, AI-агент, таск-трекер, толстый клиент редактора и три портала документации. Не то чтобы всё это нам было нужно, чтобы описать методологию управления в ИТ. Но когда однажды начинаешь собирать серьёзную базу знаний — возникает тенденция разогнаться так далеко, как только сможешь.
Единственное, что меня по-настоящему беспокоило — это конфликты слияния. Нет в мире ничего беспомощнее и безответственнее, чем методолог, пытающийся разобраться, что такое конфликт слияния. И я знал, что скоро мы в эту дрянь попадём.
Если вы когда-нибудь пробовали в одиночку причесать чужой Word-документ, в котором двадцать комментариев на полях и три уровня правок разными цветами — вы поймёте, с чего начнётся эта история. Только умножьте на 100 авторов из 60 компаний и 120 процессов. И добавьте ноль бюджета: всё это люди делают по вечерам, потому что им не всё равно, как будет выглядеть управление ИТ в стране.
Это не туториал и не обзор инструмента. Это история о том, как я полтора года уговаривал себя, что Wiki — нормальный выбор, потом ещё полгода уговаривал команду, что пора слезать. И как после переезда на Docs as Code половина того, чего я ждал, не случилась, а половина случилась не так. И почему мне всё равно нравится, что вышло.
Разбираем, как в отделе документации построили LLM-агента для автоматизированного перевода Markdown-документации. Архитектура, пайплайн, валидация, работа с Ollama, OpenWebUI и Qwen, плюсы и ограничения подхода.
С 2024 года в российской промышленности менялся подход к инвестициям в ИИ. Если еще недавно компании были готовы экспериментировать с цифровыми инициативами «на вырост», то теперь инвест‑бюджеты сокращены (а кое‑где просто порезаны), при этом требования к проектам стали кардинально жестче. Деньги выделяются на то, что дает измеримый эффект «здесь и сейчас» — на проекты с горизонтом более года года советы директоров финансирование просто не дают. При этом направлений, где ИИ окупается за 6–12 месяцев, немного, но они есть. И эта статья — про обобщение проектного опыта команды SSP SOFT в промышленности.
Если вы из тех владельцев сайтов / интернет-сервисов, которые:
• взяли образец пользовательского соглашения из интернета
• разработали пользовательское соглашение самостоятельно без привлечения юриста
• считаете, что публикация пользовательского соглашения на сайте – это формальность
то этот материал точно для вас!
Благодаря ему вы сможете:
01 понять, в каких случаях нужно использовать пользовательское соглашение, а в каких иной документ
02 понять реальную цель и ценность данного документа
03 проверить, насколько хорош ваш документ с юридической точки зрения и требуется ли его замена / доработка.
Обсуждения неудачных примеров README-файлов и документации — одна из популярных тем на профильных площадках и форумах [вкупе с другими «вечнозелеными» спорами в ИТ]. Мы в Beeline Cloud решили посмотреть, что думают о проблеме плохой документации разработчики и ученые, может ли ИИ улучшить ситуацию, что такое «нейросетевой ридмитит» — и как можно «доработать напильником» сгенерированные инструкции.
Рано или поздно сложную систему приходится объяснять человеку со стороны: новому разработчику, техлиду, архитектору или ревьюеру. И тут часто начинается боль: репозитории уже показали, основные сущности вроде бы объяснили, но всё ещё непонятно, как данные проходят через систему.
В этой части цикла я показываю, как выбрать один главный поток, проследить конкретную сущность от source до consumer и заранее привязать дебаг к слоям данных.
Внутри 4 практичных артефакта: чек-лист выбора flow, карточка сущности, таблица изменения формы данных и чек-лист точек поломки. А чтобы схема осталась в памяти надолго, я обернула её в кальмара с полипом на лице.
Привет, Хабр! Меня зовут Алиса Комиссарова, я руководитель отдела автоматизации и поддержки документирования 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.