Всё о деятельности технических писателей
Расскажем, как на наш взгляд не стоит писать функциональные требования для Технического Задания.
Напомним, что функциональные требования – это не 50% от общего объема всех требований к Системе, которые определяют 100+ % успеха разработки и реализации.
Итак, что точно не нужно делать.
Я перепробовал несколько способов вести документацию по базе данных — и у каждого были свои проблемы: информации недостаточно, сложно поддерживать, непонятна команде. Хуже всего, что плохая документация по БД тянет за собой проблемы с требованиями к данным — а это не только таблицы, но и миграции, и данные в коде. В какой-то момент я понял, что пытался решить одним документом три разные задачи.
Индустрия разработки ПО прошла долгий путь, ее бросало из крайности в крайность. Мы отказались от многостраничных технических заданий, перейдя к устным обсуждениям. Потом обсуждений стало слишком много, а системы слишком сложными, чтобы можно было описать их с помощью стикеров на доске. И мы перешли на гибридные процессы: с зоопарком инструментов и форматов описания требований, размытыми ролями и архитектурой, где паттерны перемешаны в произвольных пропорциях.
Неизменно было только одно – основную ценность представляет код. Код – это истина в последней инстанции. Требования, архитектура, тест-кейсы — не более чем черновики, наброски, которые могут быть уничтожены сразу после начала «настоящей работы» – написания кода.
Но что, если я скажу, что сейчас происходит тихая контрреволюция? Индустрия устала от неопределенности. Когда код — единственная истина, система превращается в «черный ящик». Понять, как она работает фактически, можно только прочитав тысячи строк кода.
Код идеально отвечает на вопрос «как?», но в нем нет ответа на вопросы «зачем?», «для кого?», «почему?». Без знания ответов на эти вопросы, любая доработка — это гадание на кофейной гуще.
В этой статье проследим эволюцию: от Водопада к Agile, от Agile к Гибридам и Everything as Code.
Привет, Хабр! Сегодня хотелось бы поднять актуальную тему – перевод технической документации и то, как стандартизированный английский язык может существенно упростить этот процесс.
Техническая документация чаще всего пишется на английском языке. Документацию используют международные команды и на ее основе создаются переводы и обновляются новые версии инструкций.
Со временем документация растет, ее пишут разные авторы, формулировки начинают отличаться, а терминология используется не всегда последовательно. Это делает английские тексты менее однозначными, усложняет перевод и снижает эффективность систем памяти перевода (translation memory).
С подобной задачей к нам обратились несколько клиентов, работающих с большими объемами технической документации. Чтобы стандартизировать тексты и упростить их перевод, мы начали применять подход Simplified Technical English (STE) – контролируемый вариант английского языка для технической документации. В этой статье разберем, что такое STE и как он помогает стандартизировать документацию и улучшить машинный перевод.
Всем привет! Меня зовут Катя, я развиваю Gramax — базу знаний для ИТ-команд.
Мы в команде давно и настойчиво говорим об одном: документация — это не довесок к разработке, это ее часть. Писать доку нужно до кода, вместе с кодом, а не после — когда контекст уже размылся, а решения давно забыты. Считаем, что это инженерная культура, без которой появляется куча проблем: медленный онбординг, повторяющиеся споры об уже принятых решениях, техдолг.
Один из примеров такой документации — Architecture Decision Records — короткие структурированные документы, которые фиксируют одно конкретное архитектурное решение вместе с контекстом, рассмотренными альтернативами и принятыми trade-off'ами. Ключевое слово — конкретное. ADR — это не архитектурный обзор системы и не проектная документация. Это ответ на один вопрос: «почему мы решили именно так, а не иначе?»
На эту статью меня вдохновил испанский ИИ-слоп и тред на Hacker News вокруг вопроса «как вы фиксируете ПОЧЕМУ инженерных решений, а не только ЧТО?». В статье напомню, зачем нужен ADR и какие есть стандартные проблемы. Также приведу выжимки из кейсов, в которых описаны любопытные ИИ-автоматизации.
Всем привет. Меня зовут Никита, я руковожу командой Цикл‑ОН. Мы уже более 5 лет ведем проекты по заказной разработке ПО и, как и многие, сталкиваемся с необходимостью разработки не только качественного кода, но и документацию на продукты. В нашей нише особенность, что заказчики живут в парадигме ГОСТа. Я бы здесь хотел оставить небольшую заметку о нашем опыте — как то, что для начаиналось как откровенное мучение превратилось сначала в умную идеологию, а по итогу в самостоятельное решение для подготовки документации.
Всем привет! Меня зовут Катя, я развиваю Gramax — базу знаний для ИТ-команд.
В Gramax мы делаем упор на качественную работу как человека, так и машины. И часто получаем вопросы, как автор статей может повлиять на качество выдачи ИИ-поиска.
В большей мере качество поиска зависит от нас: мы регулярно улучшаем внутренние механизмы, чтобы авторы не становились заложниками технологий. Но есть универсальные правила, которые работают в любой системе с RAG. Этими правилами и хотим поделиться в этой статье:)
Стремительное развитие ИИ в последние годы привело к невиданному росту популярности Markdown. Почти все современные LLM — от ChatGPT до Claude — по умолчанию выдают ответы в этом формате. Мы привыкли оформлять в нем заметки в Obsidian, писать промпты, вести документацию в GitHub и общаться в рабочих мессенджерах. Markdown стал «лингва-франка» современного интернета.
Но есть одна проблема. Использовать Markdown с русским языком — это боль.
Вам нужно поставить заголовок? Alt+Shift -> # -> Alt+Shift обратно. Нужно выделить код? Снова чечётка по клавишам переключения раскладки. Стандартная русская раскладка в Windows будто застряла в прошлом веке. Клавиша Shift+3 выдает нам символ №, который в 2024 году нужен крайне редко, в то время как жизненно необходимые решетки, собаки и скобки заставляют нас постоянно прыгать между языками.
Я решил эту проблему для Windows с помощью небольшого скрипта на AutoHotkey (v2).
Привет, Хабр! Меня зовут Руслан Назаров, я директор по разработке TATLIN.FLEX в YADRO. Недавно я начал возрождать культуру составления спецификаций, и она уже дает первые плоды. Мы с командой выстроили процесс работы, подобрали оптимальных участников, составили шаблоны и проверили их в работе. В этом материале расскажу, с чего начать, если в вашей компании спеки еще не написаны, и поделюсь шаблоном — его можно скачать по ссылке в конце статьи.
Документация часто устаревает быстрее, чем код. Когда знания живут в вики, чатах и головах разработчиков, интеграции начинают ломаться, а команды перестают доверять документации.
В статье разберем подход Documentation as Code, почему OpenAPI давно показал его ценность и как развитие ИИ делает структурированную документацию практически обязательной.
Дрейф модели — это риск того, что со временем ответы LLM на одни и те же входные данные начнут меняться. Для системы, которая должна давать стабильные заключения по договорам, это критично.
Привет, Хабр! На связи QA-команда мобильных секретарей — Настя и Ксюша.
Как и многие в QA, мы постоянно работаем с документацией. Ее много, она лежит в Confluence, постоянно меняется, что-то прилетает от партнеров, что-то дописывают аналитики и разработчики.
В итоге на то, чтобы собрать все воедино, проанализировать и написать качественные чек-листы или тест-кейсы, уходит много времени. В какой-то момент мы подумали: «А что, если создать AI-агента, заточенного под наши процессы, который будет делать это за нас?». Так и родился наш проект.
Рассказываем, как это было.
Разрабатываю AI-агента персональной аналитики для себя вместе с Claude Code. Любопытной инженерной задачей оказалась архитектура памяти. Как сделать, чтобы агент помнил не только последний разговор, но и паттерны, накопленные за месяцы? В этой статье описана архитектура, рабочие решения и грабли, на которые я наступила.
Если вы ещё не создавали сервис с помощью ИИ, честно, я вам завидую. Вспоминаю то чувство, которое испытывал летом 2025-го, когда начал экспериментировать с этим.
Если вы уже прочитали Часть 1 и Часть 2, то сейчас вы находитесь в одном из самых захватывающих моментов всего процесса.
И мой совет может показаться странным: остановитесь на несколько дней на этапе формирования самого первого промпта для Курсора или подобной платформы.
Это перевод статьи с opensource.com, которая мне показалась особенно полезной и практичной, поэтому решил поделиться адаптированной версией для русскоязычной аудитории. Оригинал доступен по ссылке: https://opensource.com/article/22/10/docs-as-code
В статье разбирается подход Docs as Code — способ встроить документацию в процесс разработки так, чтобы она проходила через Git, ревью и автоматическую сборку вместе с кодом. Материал будет полезен разработчикам, тимлидам и тем, кто выстраивает инженерные процессы в команде.
Помните момент, когда вы впервые попробовали ChatGPT или GitHub Copilot? У меня это было похоже на взрыв: привычные процессы рухнули, а на их месте начала формироваться новая реальность. ИИ не просто ускоряет работу — он заставляет переосмыслить сам подход к хранению и обработке информации.
Раньше я, как и многие, хранил готовые документы: Word‑отчёты, PowerPoint‑презентации, схемы в графических редакторах. Потом пришёл момент, когда я поймал себя на мысли:
«Почему я трачу время на поддержание десятков копий одного и того же текста? Почему не хранить „исходники“, а документы генерировать по мере необходимости — как сборку кода?»
Так родилась концепция, о которой я хочу рассказать.
Всем привет! Я Елена Шустерман, ведущий технический писатель в РТЛабс.
Это вторая часть статьи «Давайте сократим сокращения». Расскажу ещё немного про редактор MS Word и поиске с подстановочными знаками — об использовании фильтра с подстановочными знаками для усложненной задачи.
Пользовательское требование описывает, что нужно пользователю. Критерии приёмки — фиксируют, как это проверить. Но между «что нужно» и задачей в Jira — пропасть. Чтобы её закрыть, я пишу функциональные требования — с use case'ами, из которых тестировщик может собрать тест-кейсы, а разработчик — понять ожидаемое поведение системы.
Без хорошо проработанного и грамотно оформленного требования невозможно создать качественный IT-продукт. На что стоит обратить внимание бизнес-аналитику при подготовке требований? В этой статье в блоге ЛАНИТ я попробую подсветить эти моменты. При этом вопросы сбора и приоритизации я решил не рассматривать: будем считать, что все требования собраны.
Аннотация
С 2026 года строительная отрасль России столкнется с массовыми изменениями в оформлении проектной, рабочей и инженерной документации: введены новый национальный стандарт ГОСТ Р 21.101-2026, охватывающий строительство, реконструкцию, капремонт, эксплуатацию и ликвидацию зданий, а также отчетную техническую документацию и результаты изысканий. В параллельном процессе ужесточаются требования к формату заверения документов с переходом к полной цифровизации. С 1 марта 2026 года вступают в силу изменения в Градостроительный кодекс РФ, обязывающие использование усиленной квалифицированной электронной подписи (УКЭП) для проектной документации; использование информационно-удостоверяющих листов (ИУЛ) как альтернативы УКЭП запрещено.
Для реализации требований Минстроя о повсеместной подписи документов необходима связка отечественного ПО: КриптоПро CSP (криптопровайдер) и КриптоАРМ (графический интерфейс). В КриптоАРМ создается файл подписи, в который поочередно добавляются подписи всех участников проекта в едином файле (.sig/.p7s) через процесс соподписания. Этот подход обеспечивает соответствие новым требованиям к цифровой подписи и экспертизе документации. Также в статье рассматривается вариант использования сервиса КриптоАРМ Документы, который позволяет управлять очередностью подписей и устранить различные риски пересылки фрагментов документации по почте.