Live and recent posts from across the Fediverse tagged #документация, aggregated by home.social.
Нейросеть‑ябеда, 6000 протоколов из облака и еще 8 плагинов DokuWiki от VAS Experts
В статье «DokuWiki как платформа для технической документации: наш опыт» мы рассказали, почему ведем документацию на DokuWiki, и пообещали отдельно разобрать собственные плагины. Выполняем обещание. Всего на нашей вики работает около 35 плагинов, 10 из них мы написали сами. Далее расскажем, какую задачу решает каждый, как он устроен и что из этого получилось.
Как я собрал базу знаний и почему команда до сих пор ей активно пользуется
Записать полезную информацию на салфетке, в чате или комментарии к задаче точно лучше, чем сразу же забыть. Однако может наступить момент, когда «салфеток» стало слишком много. Мы с командой оказались именно в таком моменте и на собственном опыте узнали, что одна хорошая инструкция, на которую один сотрудник потратил несколько часов, облегчает работу всем, помогая сэкономить недели.
https://habr.com/ru/companies/rt-dc/articles/1094854/
#заметки #документация #техподдержка #база_знаний #организация_работы #управление_знаниями #инструкции #инженеры #база_знаний_поиск
[Перевод] Я не хочу читать то, чего вы не писали
Инженер Колин Брек устал читать дизайн-доки, описания PR, тикеты и письма, сгенерированные ИИ. При этом ему самому ИИ помогает писать: недавно он закончил научную статью, где ИИ сверял написанное с исходниками и логами, ловил опечатки и оформлял ссылки, а написал только аннотацию. В эссе он разбирает, почему чужой сгенерированный текст нечитаем, где ИИ в письме действительно полезен и чего он сделать не может. Читать дальше →
https://habr.com/ru/articles/1093138/
#ии #документация #pull_request #дизайндокумент #кодревью #llm #техническое_письмо #pangram
МАЯК: сначала документация, потом кнопки
Я собрал конвейер «ТЗ → канонизация → тест-дизайн → прогон» из 58 специализированных блоков с гейтами доверия: каждый критерий приёмки заземляется цитатой из исходника, серые зоны превращаются в вопросы, а не в угаданную конкретику, повторы бесплатны за счёт кэша. Проверил на синтетическом ТЗ с заложенными болезнями: 9 ловушек из 10 поймал автомат, десятую — человек с вопросником от машины; 26 вопросов стейкхолдерам за 90 секунд, 20 серых зон, 37 BDD-сценариев за 26 минут. Где платформа врёт и что не доработано — тоже в тексте.
https://habr.com/ru/articles/1093098/
#тестирование #документация #требования #qa #тестплан #llm #мультиагенты
Markdown, который вы не замечали: от двух пробелов до интерактивной статьи
Я собирался написать статью про Markdown. В процессе внутри документа оказался Doom. Разбираемся, почему два пробела меняют перенос строки, обратные кавычки не всегда спасают таблицу, а один .md по-разному выглядит на Хабре и GitHub. Прямо в статье можно менять разметку в лаборатории, решать задания и проверять результат. Есть GIF, вложенные спойлеры, маленький квест и разбор того, как упаковать ресурсы Doom в Markdown — и что на самом деле запускает игру. Читать и экспериментировать
https://habr.com/ru/articles/1091602/
#markdown #документация #doom #webassembly #freedoom #habr_flavored_markdown #gfm #интерактивный_учебник
Аналитик и ИИ: три инструмента, которые превращают хаос в требования
Мы работаем на крупном проекте, где присутствует десятки интеграций, сотни бизнес-сценариев, документация в Confluence, а теперь ещё и описания бизнес-сценариев с помощью ИИ прямо в репозиториях. Это здорово выручает для погружения в проект, но всё равно не покрывает всю картину при работе над конкретной доработкой. Поэтому в команде аналитиков мы начали заводить собственных ИИ-агентов: собираем в папку нужные репозитории из Git, БФТ от заказчика, заметки со встреч, и вместе с агентом проектируем и анализируем. Дальше в статье мы разберём полный конвейер: как готовим данные для ИИ-агента, передаём ему контекст и затем превращаем результат анализа в готовое ЧТЗ. Без нормальной подготовки на входе даже самый умный агент выдаст ерунду, а Markdown-результат на выходе ещё нужно оформить в корпоративный .docx.
https://habr.com/ru/companies/ppr/articles/1092374/
#искусственный_интеллект #markdown #аналитика #документация #git #pandoc #whisper #llm #чтз #конвертация_документов
Алгоритм терморегулирования в серверных процессорах Intel
При эксплуатации сервера пользователь сталкивается сразу с несколькими показателями температуры процессора. У него возникает ряд вопросов: какие из них имеют практическую пользу? На что ориентироваться? При какой температуре должен срабатывать алерт и когда действительно пора беспокоиться о перегреве? Под катом рассказываю про основные показатели температуры в серверных процессорах Intel и разбираю практическую пользу каждого для конечного пользователя.
https://habr.com/ru/companies/yadro/articles/1091002/
#процессоры_intel #серверы #Tprochot #TJmax #документация #терморегуляция #сервер #TCC_Activation_Temperature #THERMTRIP #DTS_Max
Как документировать API: частые ошибки и лучшие практики для создания своего руководства
Через дата-инженеров Далее проходят десятки описаний интеграций в совершенно разных форматах, даже в Excel. Формально такая API-документация есть, но пользоваться ей больно, а иногда и вовсе невозможно. Разбираем, чем «болеют» документации, как сделать понятное руководство со Swagger и без него, посмотрим лучшие практики создания API-документации. В конце — чек-лист для написания и проверки документации.
https://habr.com/ru/companies/dalee_group/articles/1089078/
#swagger #api #python #документация #документация_api #документация_it
Фронтенд и бэкенд работают отдельно. Как я связал их задачи через OpenSpec
«Посмотри эти коммиты, потом ещё вот этот фикс» — сколько раз вы так вводили AI-агента в курс командной задачи? Я организовал OpenSpec так, чтобы фронтенд и бэкенд работали в своих зонах, а контекст передавался вместе с изменениями. У каждой стороны — собственные спецификации, правила и проверки. Следующий разработчик может подхватить работу коллег без пересказа всей истории агенту. В статье разбираю, как это устроено, как синхронизироваться после нескольких задач в develop и когда фронтендер может сам сделать небольшую доработку бэкенда — и наоборот. Внутри — схема процесса, пример запроса агенту и шаблон передачи работы, которые можно адаптировать под свою команду.
https://habr.com/ru/articles/1088292/
#OpenSpec #specdriven_development #AIагенты #командная_разработка #frontend #backend #спецификации #управление_контекстом #монорепозиторий #документация
В вайбкодинге агент почти не читает документацию без ссылки: 57 файлов из 88 он не открыл ни разу
В вайбкодинге документацию первым читает агент, и открывает он почти только то, на что ему сослались. По журналам Claude Code одного моего проекта файлы без входящей ссылки агент открывал в среднем 1,2 раза, а 57 из 88 таких не открыл ни разу. Раньше документацию писали в конце цикла, и читал её человек. В вайбкодинге код пишет агент, и получает он только то, что ему подали. Я посчитал по журналам за пять недель, какие markdown-файлы агент открывал. Точкой входа ниже называю то, чем агента запускают на задачу: файлы слеш-команд в .claude/commands и описания субагентов в .claude/agents . Документы, названные в точке входа, агент открывал в среднем 12,3 раза.
https://habr.com/ru/articles/1088144/
#сезон_Код_будущего #вайбкодинг #claude_code #CLAUDEmd #AGENTSmd #ии_для_документации #ии_для_вайбкодинга #документация #ИИагенты #контекст
Как мы создаём ИИ-агента для технических писателей (и почему это непросто)
Привет, на связи команда документирования СберТеха и авторы этой статьи — Маша Бурханова, Лида Ковач и Саша Яковлев. Мы уже рассказывали , как создали глоссарий ИТ-терминов в удобном для разработки документации формате и с какими трудностями при этом столкнулись. Мы поняли: главная проблема технического писателя — это даже не отсутствие правил, а их соблюдение. Представьте, что у вас есть больше 700+ терминов, а в коде на каждую десятую строчку приходится ошибка. Исправлять вручную — всё равно что пешком подниматься на 150-этажный небоскреб. У нас родилась идея: проверять текст прямо во время написания, в редакторе. Расскажем, как за несколько часов собрали прототип ИИ-агента технического писателя, с какими «подводными камнями» столкнулись при переходе к промышленной эксплуатации и почему в итоге написали собственное решение на Python.
https://habr.com/ru/companies/sberbank/articles/1085230/
#сбертех #документация #документирование #ии #ииагенты #искусственный_интеллект #агент #глоссарий #терминология
110 тестов, которые не проверяют код: как заставить документацию падать вместе со сборкой
В своей же справке я нашёл фразу, которая была неправдой. Не устарела - была неправдой с самого начала. Дальше про то, как сделать так, чтобы кодовая база физически не могла врать в документации, и почему главная сложность тут не в тестах, а в списке исключений.
Почему ИИ для программирования выбирает одни и те же библиотеки: я просканировал 30 сайтов документации
Я собираю фидбэк по проекту, который советую людям как альтернативу тяжёлому фреймворку. Вставляю его в диалог с ассистентом кода и прошу подсказать библиотеку под задачу, которую он решает лучше всего. Ассистент называет три конкурента покрупнее и ни разу — мой проект. Дело не в качестве кода: я решил проверить гипотезу техническими средствами, а не спором в комментариях. Гипотез было три. Может, дело в файле robots.txt , который блокирует ботов ИИ. Может, у проекта просто нет llms.txt — модного файла, который сейчас советуют выкладывать. Может, документация физически нечитаема для краулера. Я написал скрипт, прогнал его на 30 сайтах документации популярных Python- и JS-библиотек и получил цифры, которые сходятся не с той гипотезой, что я держал в голове изначально. Коротко результат: robots.txt не блокирует ботов ИИ ни на одном из 30 доменов — ни по адресу документации, ни в корне домена; llms.txt есть у 11 проектов, и независимые логи показывают, что его почти никто не запрашивает; а пустая для краулера страница нашлась у трёх проектов, но после проверки внутренних страниц из них остался один. Метод, код и таблица — дальше, вместе с сопоставлением с чужими исследованиями и командой, которой это можно проверить у себя.
https://habr.com/ru/articles/1084456/
#сезон_Код_будущего #ии_для_программирования #нейросеть_для_программирования #llms_txt #llmsfulltxt #open_source #документация #GPTBot #AIкраулеры #robotstxt
RAG, поиск и LongContext: почему сложные пайплайны не всегда нужны
В 2023 году RAG был единственным способом засунуть знания в LLM — контекстное окно было маленьким, часто были галлюцинации. RAG постепенно стал одной из самых популярных технологий, чтобы получить базу знаний, по которой можно искать данные через натуральный язык. Но с другой стороны — RAG-пайплайн тяжёлый и трудозатратный. Компания хочет чат по своей документации. Разработчик говорит: нужен пайплайн — чанкинг, эмбеддинги, векторная база, реранкер. Два-три месяца работы плюс сервис, который надо вечно поддерживать, ради 400-страничной документации. И всё это занимает месяцы, тратит ресурсы ради не такой уж и большой выгоды. Сегодня многие модели держат 1M токенов, а то и больше, а в это окно контекста чаще всего спокойно влезает вся документация. Но если не влезет — то обязательно ли сразу строить весь RAG самому? А как понять, когда есть альтернатива RAG, а когда нет? В этой статье мы разберём, почему RAG стал выбором по умолчанию (и почему это было оправдано), посмотрим, как падает качество при Long Context, сравним подходы и узнаем, что, как и когда использовать.
https://habr.com/ru/companies/bothub/articles/1081080/
#документация #техническая_документация #RAG #LLM #longcontext #AI #ИИ #arxiv #эмбеддинги #поиск
[Перевод] ИИ для передачи дел: как найти знания, которые уходят из компании вместе с техлидом
Документация редко отражает всю картину проекта. Самые важные решения часто остаются в переписках, памяти команды и привычках одного человека. На примере собственного ухода из компании я расскажу, как использовать ИИ-агентов для аудита знаний, поиска слепых зон и подготовки передачи дел — и почему даже идеальная wiki не заменяет профессионального опыта. Разобрать подход
https://habr.com/ru/companies/otus/articles/1080722/
#искусственный_интеллект #ИИагенты #агентные_системы #передача_знаний #bus_factor #автоматизация_разработки #документация #управление_знаниями #техническое_руководство
SpecaFlow — больше чем SDD
Вайбкоддинг быстро обнажил своё главное слабое место. Как только у проекта появляется реальный потребитель, встаёт вопрос ответственности за его качество. А качественное развитие проекта в глубину невозможно без экспертизы в архитектуре и бизнес‑решениях: модели ИИ хороши в генерации по одному промпту, но теряют свою суперсилу на длинных дистанциях. Планирование продлевает жизнь проекта, который развивается с ИИ, но и это тупиковая ветвь: продукты бывают очень большими и сложными, я это знаю из опыта в бигтехе и госах. Трудно представить начало сессии с ИИ, в которой модель легко и быстро понимает весь проект и необходимый контекст, чтобы принять от разработчика требования и качественно спроектировать внедрение, не сломав текущее стабильное состояние. Экспертиза инженера‑разработчика или системного аналитика несравненно качественнее — хотя бы потому, что он живёт с ней 24/7.
https://habr.com/ru/articles/1080730/
#spec_driven_development #specaflow #aiагенты #harness #автоматизация_разработки #документация
Две строки в справке Яндекс 360, из-за которых архив писем работает не так, как выглядит
Поиск в архиве писем Яндекс 360 выдаёт снимок на момент запуска: справка пишет, что каждый поиск срабатывает один раз и выдача больше не обновляется, а обновить её можно двумя ручными способами. Вторая граница - в журнале архива: действия уволившегося администратора там сохраняются, но задать его в фильтре по сотрудникам нельзя, потому что в фильтре только действующие. Разбор идёт по пяти страницам справки и по справочнику API 360, с цитатами и датой сверки. Что написано на пяти страницах справки
https://habr.com/ru/articles/1078342/
#Яндекс_360 #архив_писем #корпоративная_почта #журнал_действий #аудит #расследование_инцидентов #оффбординг #документация
вендора
Как я держу документы и инструкции для агентов в актуальном состоянии
Цепочка такая: Сессия заканчивается. Транскрипт остаётся на диске. Хук SessionEnd только ставит session_id в очередь ( enqueue ). Текст уроков он не пишет. Systemd-таймер agent-learn-distill раз в ~30 минут будит distill.py . Скрипт берёт сессию из очереди или простаивающую. Если с последнего обновления ещё нет примерно 25 минут простоя и сессия не в очереди — ждёт. Нужно минимум два хода пользователя, иначе пропуск и повтор позже. Строит выдержку из chat_history : до 12 ходов пользователя и до 4 коротких хвостов ассистента (лимит около 24k символов), не весь сырой транскрипт. Дальше вызывает Grok без интерактива, с готовым промптом и JSON-схемой. В промпт уже вложены текущий LEARNED.md , заголовок сессии и выдержка; модели нельзя звать инструменты и перечитывать файлы. На выход: либо skip , либо новый полный LEARNED.md (замена целиком, до ~80 строк и ~8k символов: живое оставить, устаревшее и дубли выкинуть; дата сверху, русский, без дампов кода) плюс список уроков с метками learned / gotcha / decision . Тот же текст зеркалится в секцию Auto-learned файла MEMORY.md проекта. Уроки с меткой learned уже в теле LEARNED.md ; gotcha и decision уходят в inbox на воскресный подъём в общие инструкции. В живой сессии тот же прогон можно форсировать командой /learn .
https://habr.com/ru/articles/1079304/
#агенты #документация #llm #искусственный_интеллект #автоматизация #devops #code_review #markdown #systemd #knowledge_management
Как мы автоматизировали перевод технической документации через инструменты вокруг модели
Рассказываем, как мы автоматизировали перевод технической документации и построили отдельный слой вокруг LLM, который выполнял главную работу.
https://habr.com/ru/companies/bitrix/articles/1078450/
#техническая_документация #документация #технический_писатель #перевод_документации #машинный_перевод #локализация #llm #python #markdown #автоматизация
Миграция Power BI → Apache Superset: что переносится на самом деле
На Apache Superset я перенёс один отчёт. Одна таблица, пара графиков, день работы. Это была годовая цель: показать, что умею. Пользуются при этом по-прежнему исходной версией в Power BI. Перенос в компании идёт всерьёз: есть коллеги, которые публикуют на Superset отчёты десятками. И чем ближе отчёт к одной таблице, тем легче он едет. Мои — не такие. Поэтому я открыл свою самую тяжёлую модель — 22 таблицы, 206 колонок, 86 мер — и прочитал её целиком. Двадцать мер из восьмидесяти шести меняют расчёт в зависимости от того, до какого уровня развернули матрицу: из-за них сверка «итог в итог» после переноса сходится идеально и ничего не доказывает. Шесть производственных договорённостей зашиты прямо в формулы и не описаны больше нигде. Разбираю, что на самом деле переносится при миграции BI и почему документацию в ландшафте на 800+ отчётов придётся отдавать машине.
https://habr.com/ru/articles/1079018/
#Power_BI #Apache_Superset #DAX #миграция_BI #импортозамещение #документация #LLM #теория_ограничений
Виртуальные сотрудники вместо ИИ-помощников: как агенты учатся работать внутри компании
Разработка постепенно меняет привычное разделение работы между человеком и инструментами. ИИ берет на себя не отдельные операции, а последовательность действий, для которой раньше требовалось участие специалиста. Но вместе с ростом автономности меняются и требования к самой системе. Агент должен понимать контекст проекта, знать внутренние правила и иметь доступ к инструментам, с которыми работает команда, а не просто искать информацию и писать код. Эту тему подробно разобрали на восьмом митапе MWS для DevOps и SRE. Эксперты из MTC Web Services и Orion Soft показали разные стороны перехода к агентной разработке и поделились кейсами, как ИИ потихоньку превращается в виртуального сотрудника — агента, действующего без постоянного сопровождения человека, и что для этого приходится менять в инженерных процессах.
https://habr.com/ru/companies/ru_mts/articles/1075826/
#виртуальный_сотрудник #ИИагент #контекст #оркестрация #корпоративные_знания #документация #автоматизация #МТС #проверка_решений #DevRails
DokuWiki как платформа для технической документации: наш опыт
Когда технической документации становится много, она перестает быть просто набором инструкций и справочных материалов. Она превращается в базу знаний компании, к которой обращаются как опытные специалисты, так и новички. И платформа для ее хранения должна не только вмещать большие объемы информации, но и помогать структурировать знания, быстро находить нужные материалы и не запутывать читателя. Меня зовут Лена, я технический писатель в VAS Experts. В компании документация хранится в DokuWiki и размещена на двух площадках. В этой статье расскажем, почему для этой задачи мы выбрали именно платформу DokuWiki и какие собственные инструменты добавили поверх стандартных возможностей.
README врёт: как я сделал open‑source линтер, который сверяет документацию с реальным репозиторием
README редко ломается в один момент. Обычно он просто постепенно перестаёт соответствовать проекту: переименовали команду, перенесли файл, удалили .env.example , сменили package manager — а инструкция осталась прежней. В итоге новый пользователь копирует команду из README и получает ошибку. Разработчик же часто узнаёт об устаревшей документации только после issue, сообщения коллеги или неудачного деплоя. Мне стало интересно: можно ли автоматически находить хотя бы часть таких расхождений, не выполняя команды из README и не отправляя исходный код в LLM? Так появился RealityLint — open‑source CLI, который статически сверяет проверяемые утверждения из README с реальным состоянием репозитория.
https://habr.com/ru/articles/1072076/
#RealityLint #README #Python #GitHubActions #CICD #opensource #статическийанализ #документация #тестирование #линтер
Мы мигрировали сотню страниц документации через MCP-сервер, а не скриптами
У каждого опубликованного сайта GitBook уже есть MCP-сервер. Мы узнали об этом случайно и вместо конвертеров просто дали агенту ходить в документацию напрямую — сотня страниц переехала на Diplodoc за четыре дня. Что агент сделал сам, где проходит граница его возможностей и какие десять вещей пришлось доделывать руками.
https://habr.com/ru/articles/1071650/
#MCP #AIагенты #документация #docsascode #Diplodoc #GitBook #миграция #markdown #техническая_документация #YFM
Почему агентный SDD ломается между микросервисами?
Каждая команда описала свой сервис, каждый агент точно выполнил локальную спецификацию, все контракты прошли проверку — а сквозной процесс всё равно развалился. Проблема не обязательно в коде: часто у системы нет общего контекста, владельца инвариантов и правил частичного отказа.
https://habr.com/ru/articles/1066242/
#SDD #микросервис #агент #AI #AIагент #API #Документация #Требования #ТЗ
Как мы описали 15 000 таблиц за полгода вместо 500 за год — и перестали писать документацию руками
Годы идут, но что‑то остаётся неизменным: писать документацию никто не любит, но тем не менее все почему‑то ругают тех, кто её не пишет. В Яндексе одних только таблиц с данными — десятки миллионов, общим объёмом в экзабайты данных. Даже когда мы оставляем из всего этого количества только самое востребованное, остаётся несколько десятков тысяч таблиц, которые кто‑то должен описать словами: что внутри, откуда взялось, можно ли этому доверять. Без таких описаний аналитик не находит данные через поиск, не понимает, что лежит в таблице, и заново собирает то, что уже собрал коллега. И страдает не только человек: ИИ‑агенты, которые всё чаще сами решают аналитические задачи, на неописанных данных также теряют в качестве — чем меньше известно про таблицу, тем хуже результат. Год мы уговаривали людей описывать таблицы вручную — и собрали описания всего на 500 таблиц из 40 тысяч. Если описывать все данные с такой скоростью (при учёте, что постоянно появляются новые) — страшно представить, на сколько десятков лет мог бы растянуться этот процесс. Меня зовут Роман Гриднев, я технический менеджер в Яндексе. Расскажу, как мы научились не писать документацию. «Не писать‑то все могут», — скажете вы. Но мы подключили к задаче LLM и дали людям вместо чистого листа черновик: пусть с ошибками, зато не пустую страницу, которая пугает. За полгода мы так описали 15 тысяч таблиц и сэкономили около пяти лет рабочего времени аналитиков. Со временем качество черновиков от LLM доросло до почти полного соответствия описаниям, сделанным людьми.
[Перевод] Вашему ИИ‑агенту нужна карта: LLM Wiki или README достаточно
В своей предыдущей статье об инструментах и агентах искусственного интеллекта я рассмотрел инструменты, которые меняют подход к разработке программного обеспечения. В последующей статье я утверждал, что роль разработчика смещается от написания кода к его управлению. В этой статье делается следующий шаг: что произойдет, когда агенты ИИ станут способны создавать и перемещаться по все более сложным кодовым базам? Как нам поддерживать точность, доступность и актуальность знаний, на которые они опираются? Именно здесь на помощь приходит идея вики-проекта для магистерских программ.
Как QA я все равно пишу документацию, но с ИИ трачу на нее часы, а не дни
В статье я расскажу, как решал проблемы погружения в проект сначала вручную, а потом с помощью ИИ-инструментов и как мне удалось сократить путь от дней и недель до нескольких часов. Мой опыт пригодится QA-инженерам, которым приходится разбираться в новых проектах, систематизировать знания о продукте и поддерживать документацию в актуальном состоянии.
https://habr.com/ru/companies/cloud_ru/articles/1062556/
#тестирование #qa #rag #искусственный_интеллект #документация
Как мы показываем клиентам документацию по проекту из приватного репозитория, не пуская их в репозиторий
Сразу дисклеймер: это рассказ про инструмент, который мы написали для себя и используем каждый день. Ссылку дам в конце, продавать не буду — расскажу про проблему и как её решали, потому что упираемся в неё, возможно, не только мы. За последний год мы переписали почти всю проектную документацию в markdown и положили в тот же git, где лежит код. Причина простая: после перехода на Cursor и Claude Code так было удобнее работать. Модели нормально обрабатывают markdown и не лопатят десятистраничный google-док, диффы видно в PR, доки лежат рядом с кодом, который описывают. Всегда можно обратиться к инфе по проекту, внести обновления - короче пользоваться документом, а не хранить его для красоты. И тут вылезла проблема, о которой лично мы заранее не подумали: документацию читает не только тот, кто её пишет. Её читают клиенты, менеджеры, дизайнеры, эйчары. А они в репозиторий не полезут никогда. Дать клиенту доступ в GitHub/GitLab — так себе затея сразу по нескольким причинам: там лежит то, что ему видеть не надо, это лишний разговор про безопасность, да и сам интерфейс гитхаба человека не из айтишки отпугивает. Плюс требуется регистрация. В итоге мы делали то же, что, по-моему, делают все: копировали markdown в google docs, чтобы клиент мог прочитать и покомментировать, а потом при каждом изменении заново выгружали и сводили комментарии руками. Год так жили. Что смотрели, прежде чем пилить своё: GitBook и Mintlify хотят, чтобы ты писал в их редакторе. Ради шеринга пришлось бы бросить тот самый workflow, ради которого мы в git и переехали. Плюс ценник.
https://habr.com/ru/articles/1061946/
#документация #docsascode #markdown #git #MCP #GitHub #GitLab #техническая_документация #комментарии_к_документации #AIагенты
Одна ошибка, и ты ошибся: как сохранить доверие к ИТ-продукту
Привет, Хабр! Меня зовут Мария, я технический писатель в ИнфоТеКС. Представьте: вы запускаете новое приложение, тщательно проработанное, с инновационными возможностями и безупречным дизайном. Пользователь открывает описание функции и встречает ошибки. Например, «Выберите цепочку, содержа ЩЕЕ правило». Что происходит в этот момент? Небольшая опечатка, грамматическая ошибка или стилистическая неточность — и доверие к продукту подрывается, а значит, и к вашей компании. Проблема в том, что даже единичная небрежность в документации может свести на нет все усилия по созданию качественного продукта. Ведь небрежность в документации сразу бьёт по доверию: если текст не вычитан, то насколько надёжен сам продукт? Чтобы такие ситуации не доходили до пользователей, в ИнфоТеКС выстроена система ревью, где ошибки выявляются и исправляются до публикации. Однако мы решили пойти дальше и посмотреть на ошибки системно — чтобы не просто править, а предотвращать их ещё на этапе создания черновика. Именно для этого провели «работу над ошибками» и проанализировали, какие недочёты возникают чаще всего.
https://habr.com/ru/companies/infotecs_tech/articles/1060264/
#инфотекс #тхническое_писательство #документация_проекта #документация_кода #документация_на_по #документация_it #документация_по #документация
Фундаментальная проблема бизнеса — отсутствие документации.
https://www.golubev.by/2024/02/fundamental-business-problem.html