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

Привет!

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

Если хочет — может раскрыть больше деталей, если нужно наоборот — может скрыть избыточные.

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

Будет PlantUML, JavaScript, HTML и немного разочарования в ИИ :-)

P.S. Не смотрите на то, что читать статью якобы много-много минут. Текста там не много, все код виноват :-)

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

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

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

Когда я узнал, что Anthropic публикует 250-страничный технический документ для модели, которую не пустили в паблик с пометкой «вооружен и опасен», подумалось, что такое стоит читать целиком.

Не ради хайпа про хакерский AI, а ради понимания, куда движется вся индустрия и что это означает для тех, кто строит продукты на основе больших моделей сегодня. Я уже уверен, что это — один из самых важных документов на сегодня.

В этой статье на примере продуктов Контура разберём, зачем нужен глоссарий, какую пользу он даёт и как внедрить его в свою документацию.

Если вы решили внедрять искусственный интеллект в ваш проект, то скорее всего наступит момент когда потребуется технические задание. Так как внедрять ИИ часто начинают уже «прокачанные» пользователи ChatGPT, то возникает соблазн отдать написание этого самого ТЗ самому ИИ. А возможно еще и разослав это ТЗ разным исполнителям, оценить с помощью ИИ их предложения. Что может при этом пойти не так, разберем в этой статье.

Статья может помочь разработчику, если ваш начальник или клиент создал ТЗ с помощью ИИ найти аргументы почему этого недостаточно (хотя не факт, что они помогут), или руководителю, использующему ИИ и планирующему внедрение ИИ в организацию

В статье есть: какие проблемы могут быть в сгенерированном ИИ ТЗ на внедрение ИИ (с примерами), к чему приведет его использование и небольшой совет для чего все-таки можно использовать ИИ при подготовке ТЗ

Хабровчане, приветствую! Меня зовут Михаил Казанцев, я ведущий системный аналитик в мобильном приложении Вайлдберриз. Работал и писал требования как в стартапах с монолитами, так и в банковском секторе с сотнями сервисов в одном контуре, рассказать есть что.

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

Вы открываете чат. Загружаете договор на 80 страниц или корпоративный регламент на 200. Пишете: «Добавь в раздел 4.2 новый пункт про порядок согласования».

AI читает весь документ целиком. Находит (или не находит) нужное место. Что‑то вставляет. Иногда попадает, иногда — нет. Иногда ломает форматирование соседних таблиц. Иногда забывает, что этот же раздел нужно синхронизировать с приложением.

Дело не в мощности модели. Дело в том, что она работает вслепую: нет карты документа, нет правил редактирования, нет понимания что с чем связано или неприкосновенно.

Адепты Agile‑манифеста зачастую весьма скептически относятся к процессу формирования документации на программных проектах. Как нельзя лучше это отношение сформулировал один эффективный перспективный руководитель отдела программирования, выпускник факультета менеджмента, который охарактеризовал документацию как «кучу макулатуры, которая генерится техписом и сдается в архив». В ту пору, когда я был молодым и перспективным, я тоже так думал. Но, как говорится, время лечит.

Статья носит исключительно образовательный/ознакомительный характер. Она не служит цели, рекламировать какой-либо инструмент или ПО. Все наименования программного обеспечения, упомянутые в статье приведены из личного опыта.

На днях прислали в рабочую почту очередное ТЗ в Word на разработку, для комментирования и оценки реализации. При том что у нас есть корпоративный Confluence - мощнейшая система, как раз предназначенная для коллективной работы.

Почему многие до сих пор продолжают изначально использовать Word как основу для обмена информацией?

Привет, Хабр! Мы уже разбирали OVN в связке с OpenStack и трассировку пакетов. А сегодня предлагаем почитать перевод документации про Quality of Service (QoS) в Neutron: что это, какие правила поддерживаются, как настроить и как работать с политиками.

Работая над большими проектами рано или поздно сталкиваешься с типовой проблемой: меняются команды, приходят новые люди, требования плывут, правки копятся в разных файлах и комментариях в Confluence. В одном разделе — одна версия ролей, в другом — другая. Описания функций разорваны, шаблоны не соблюдаются, а критичные решения записаны «на полях». Так и рождается хаос. Не потому, что кто-то плохо работал, а потому что в большом проекте с долгой жизнью и множеством участников документация неизбежно расползается.

Поэтому мы сделали своего ИИ-ассистента «ДокАрхитектор» — и в этой статье расскажем, как обучить нейросеть корпоративным стандартам, сократить время проверки ТЗ с 10 часов до 3–4 и перестать бояться унаследованных проектов.

Самый эффективный способ — не создавать её вообще. Как известно, самая плохая документация лучше, чем никакой.

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

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

Привет, я — Александра, юрист для 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. У каждого инструмента и подхода есть свои плюсы и минусы. Выбор зависит от множества факторов: сложности, требований к результату, потребителя контента, бюджета отдела, объема накопившегося легаси — да и просто моды в профессиональной среде.

Но что если посмотреть на вопрос с другой стороны? Что если выбирать и проектировать систему документирования исходя из того, сколько свободы предоставляется техническому писателю?

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