Всё о деятельности технических писателей
Привет, я — Александра, юрист для digital-агентств и фрилансеров! Специально для всех владельцев сайтов я подготовила подробную статью о том, какие юридические документы должны быть на каждом сайте в зависимости от его вида и наполнения. Прочитав её, вы точно всё поймёте.
Привет! На связи Наталья Нефедова — менеджер продукта и head of сообщества техписателей в Cloud.ru.
В 2024 году у нас в компании произошла реорганизация, после которой мы, техписатели, перестали находиться в матричной структуре, а распределились по продуктовым командам («изюм в булке») и нашими руководителями стали менеджеры продуктов. В этой новой реальности экспертиза и профессия техписателя как таковая стали размываться, нам надо было каким-то образом это остановить. И в этом нам помогло сообщество, которое не только обратно объединило профессию техписаталей, но и влияет на бизнес-цели компании.
Наш опыт создания сообщества оказался объемным и насыщенным, поэтому поделюсь им в трех частях. Материал будет интересен, если у вас еще нет сообщества и вы хотите его создать, или оно уже есть и вы хотите попробовать новые механики, чтобы повысить его эффективность.
В первой части расскажу про минусы «изюма в булке» для нашей компании, а также про дизайн и операционную модель нашего сообщества.
Разработка документации на создаваемые ИТ-продукты – это не только «правила хорошего тона», но и насущная необходимость. Ведь без технического задания невозможно зафиксировать требования к продукту, без руководства пользователя сложно грамотно продуктом пользоваться, без технической документации, описывающей продукт, сложно будет искать и исправлять ошибки и проводить необходимые доработки, когда в них возникнет необходимость, и т.д.
Обычно документацию делают по одному из двух путей – либо используют стандарты, описывающие требования к составу, структуре и содержанию документов (например, ГОСТ 19-й и 34-й серий – ЕСПД и КСАС), либо самостоятельно разрабатывают документ, создавая его на основе собственного опыта или по существующим образцам, в т.ч. взятых из интернета.
Но как же её правильно сделать?
Мой ответ - начинать надо с синопсиса документов.
Около 90% фронтенд‑разработчиков в нашей команде используют ИИ‑помощников для написания кода. Лично у меня — и как я могу заметить, у многих — был такой опыт: вы только начинаете пользоваться ИИ‑помощником, просите его сгенерировать какое‑нибудь классное MVP, получаете результат минут за пять и думаете: «Вау, неужели это возможно? Как это вообще работает и как это круто».
А дальше вас ждёт сюрприз.
Всем привет, меня зовут Валерий Баранов, я руковожу командой технологий фронтенда в Яндекс 360. Мы занимаемся тем, что сами называем «общим фронтендом»: общими техническими компонентами, общим CI/CD, платформами дистрибуции общих компонентов. Сегодня я хочу рассказать, как мы в Яндекс 360 сделали фронтенд‑проекты по‑настоящему AI‑ready: научили ассистентов понимать структуру наших репозиториев, работать с внутренними библиотеками и даже соблюдать паттерны дизайн‑системы.
Привет, хабр! Решил поделиться с миром своим проектом, который делался в свободное время и был мне полезен на моей текущей работе. Ссылка на гитхаб https://github.com/simplepersonru/SimpleOntoDoc
Проект - генератор статического сайта документации для онтологической модели данных
Онтологическая модель данных — это способ формального описания предметной области, в основе которого лежат три главные вещи:
1. Классы (типы объектов, «сущности»).
2. Атрибуты (свойства этих классов).
3. Связи (отношения между классами).
Под катом:
+ Мотивация (зачем мне это нужно)
+ Как это выглядит (с опубликованным примером)
+ Как можно применить (зачем Вам это нужно)
AI дисклеймер - при написании статьи активно использовалась нейросеть головного мозга, будьте осторожны
Лавинообразный рост информации превратил привычный Ctrl+F в артефакт прошлого. Мы открываем тяжёлые PDF-файлы, зарываемся в десятки вкладок, пытаясь выудить одну нужную строчку, и тратим на это часы, которых и так вечно не хватает.
Но времена меняются. На смену ручному поиску приходят умные сервисы, которые умеют не просто искать, а анализировать, обобщать и выдавать готовую выжимку по запросу. Они работают с веб-страницами, документами, научными статьями, а иногда и с тем и другим одновременно.
В этом обзоре мы собрали самых интересных игроков на этом поле:
• BotHub,
• Brave Search,
• ChatPDF,
• “ГигаЧат”,
• Felo AI,
• iAsk,
• Komo,
• Perplexity
• и DuckDuckGo –
Всё, чтобы вы могли выбрать идеальный инструмент для своей задачи – будь то быстрый ответ или глубокое исследование. Готовьте свои самые сложные документы и вопросы – сейчас будем разбираться, кто из них действительно умеет искать иголку в стоге сена. Узнайте, как превратить хаос информации в стройную систему с помощью ИИ.
Документацию можно готовить где угодно и как угодно. Писать инструкции в многочисленных CCMS, публиковать сайты через генераторы наподобие Sphinx, применять сложные разметки вроде DITA, вести базы знаний в Confluence или вообще собирать файлы в Word. У каждого инструмента и подхода есть свои плюсы и минусы. Выбор зависит от множества факторов: сложности, требований к результату, потребителя контента, бюджета отдела, объема накопившегося легаси — да и просто моды в профессиональной среде.
Но что если посмотреть на вопрос с другой стороны? Что если выбирать и проектировать систему документирования исходя из того, сколько свободы предоставляется техническому писателю?
Давайте выкрутим регулятор свободы на максималку сначала в одну сторону, когда техпис не имеет абсолютно никаких рамок и ограничений, а затем в противоположную, когда он тотально несвободен. Какие преимущества будут у каждой из этих двух крайностей и какие выводы можно будет сделать по итогу такого мысленного эксперимента — об этом моя статья.
Когда вы последний раз читали документацию размером более страницы А4 без привлечения LLM? Вопрос риторический.
Кажется пришло время вычеркнуть написание документации из списка тех. долга.
В статье я попытался переосмыслить саму идею документации для enterprise разработки, а также рассказать о практическом решении поднятого вопроса для любой системы на платформе 1С 8.3 и выше.
Расскажем, как на наш взгляд не стоит писать функциональные требования для Технического Задания.
Напомним, что функциональные требования – это не 50% от общего объема всех требований к Системе, которые определяют 100+ % успеха разработки и реализации.
Итак, что точно не нужно делать.
Я перепробовал несколько способов вести документацию по базе данных — и у каждого были свои проблемы: информации недостаточно, сложно поддерживать, непонятна команде. Хуже всего, что плохая документация по БД тянет за собой проблемы с требованиями к данным — а это не только таблицы, но и миграции, и данные в коде. В какой-то момент я понял, что пытался решить одним документом три разные задачи.
Индустрия разработки ПО прошла долгий путь, ее бросало из крайности в крайность. Мы отказались от многостраничных технических заданий, перейдя к устным обсуждениям. Потом обсуждений стало слишком много, а системы слишком сложными, чтобы можно было описать их с помощью стикеров на доске. И мы перешли на гибридные процессы: с зоопарком инструментов и форматов описания требований, размытыми ролями и архитектурой, где паттерны перемешаны в произвольных пропорциях.
Неизменно было только одно – основную ценность представляет код. Код – это истина в последней инстанции. Требования, архитектура, тест-кейсы — не более чем черновики, наброски, которые могут быть уничтожены сразу после начала «настоящей работы» – написания кода.
Но что, если я скажу, что сейчас происходит тихая контрреволюция? Индустрия устала от неопределенности. Когда код — единственная истина, система превращается в «черный ящик». Понять, как она работает фактически, можно только прочитав тысячи строк кода.
Код идеально отвечает на вопрос «как?», но в нем нет ответа на вопросы «зачем?», «для кого?», «почему?». Без знания ответов на эти вопросы, любая доработка — это гадание на кофейной гуще.
В этой статье проследим эволюцию: от Водопада к Agile, от Agile к Гибридам и Everything as Code.
В какой-то момент я прогнал самоаудит по своему проекту и получил неприятную, но полезную картину.
В кодовой базе оказалось 41 034 метода и 2 170 файлов. Если считать только основной код, без тестов, 12 093 метода из 19 880 были вообще без комментариев. Покрытие документацией получилось 39%.
Это не история про чужой легаси-проект. Это мой текущий код. Он просто рос быстрее, чем я успевал его объяснять.
На бумаге у меня всё было нормально: README, заметки по архитектуре, большой CLAUDE.md, отдельные пояснения по важным решениям. Но когда смотришь на реальные вопросы, которые возникают по ходу работы, быстро выясняется, что документация покрывает только часть из них.
Привет, Хабр! Сегодня хотелось бы поднять актуальную тему – перевод технической документации и то, как стандартизированный английский язык может существенно упростить этот процесс.
Техническая документация чаще всего пишется на английском языке. Документацию используют международные команды и на ее основе создаются переводы и обновляются новые версии инструкций.
Со временем документация растет, ее пишут разные авторы, формулировки начинают отличаться, а терминология используется не всегда последовательно. Это делает английские тексты менее однозначными, усложняет перевод и снижает эффективность систем памяти перевода (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 на одни и те же входные данные начнут меняться. Для системы, которая должна давать стабильные заключения по договорам, это критично.