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

Всем привет! Меня зовут Катя, я развиваю Gramax, open source-платформу для управления технической документацией.

В нашем чате и у пользователей регулярно встает вопрос переезда в Gramax c других платформ. Переезд с Confluence и Notion мы сделали прямо в интерфейсе приложения, а с Yandex Wiki — отдельной утилитой. Нет, мы не поленились, просто заметили, что сообщество Yandex Wiki такое давно просит: пример №1 (367 голосов), пример №2 (874 голоса).

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

Ну хорошо, не поразило. Но понравилось настолько, что я записала это в свой блокнот, а теперь, спустя 13 лет, делюсь с вами. Если вы работаете с документацией, интерфейсами или пишете ТЗ или bug reports, эти заметки будут вам полезны. Кстати, вот первая часть статьи — взгляните, если пропустили.

Diplodoc — опенсорс‑платформа для работы с документацией в парадигме Docs as Code, которая создаётся в Яндексе силами команд Yandex Infrastructure и Yandex Cloud и является частью наших опенсорс‑инструментов. С её помощью мы собираем всю документацию компании. Это суммарно более 300 тысяч статей в более чем 2500 документационных проектов и порядка 6000 запусков Diplodoc CLI каждый день.

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

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

Больше всего от растущего времени сборки страдали технические писатели: для просмотра внесенных изменений им требовалось собирать документацию целиком и на больших проектах это стало приводить к ожиданию более 10 минут. С десятками тысяч правок документации ежедневно эти десятки минут складываются в человеко‑месяцы простоя, которые никому не идут на пользу. Поэтому мы приняли решение всё это основательно причесать.

Привет, Хабр! Я Александр Зырянов, проектный менеджер TMS с открытым исходным кодом TestY. Сразу о главном: выложили в open source версию TestY 2.1. 

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

Какие еще изменения ждут пользователей в TestY 2.1 — читайте под катом.

А вы никогда не задумывались, почему, с одной стороны, у нас появляются всё более крутые и мощные инструменты для разработки? На бэкенде мы можем делать микросервисы, писать офигительные SPA-приложения — но при этом будто бы сама программа становится всё хуже и хуже.

Каждый раз происходит одна и та же история: мы хотим сделать как лучше, но код в итоге всё равно превращается во что-то странное и не поддерживаемое.

Откуда берётся эта эрозия программного обеспечения? Почему так выходит, что новые технологии не только не помогают, но иногда даже мешают нам писать качественные программы? Почему, когда мы стараемся делать хорошо — получается плохо?
И главное — что с этим делать?

«А в ТЗ этого не было!» — знакомая ситуация?

Проблема, которая часто возникает: ТЗ составляются формально, без должной детализации — слишком абстрактно, без примеров или с пробелами в логике.

Когда я стала администратором чата, мне казалось, что это будет ответственно, но весело, как прогулка в лесу в воскресный день: удалять ненужное, поддерживать участников, отвечать на вопросы. Однако совсем скоро я столкнулась с тем, с чем не ожидала столкнуться — со своим собственным недовольством. Участники раздражали тем, что задавали одни и те же вопросы. Важная информация раздражала тем, что терялась в потоке. Мой FOMO не уменьшался, а рос. А моё Избранное в Телеграме разбухало от пересланных сообщений, которые я никогда не перечитаю.

Хотел бы представить для обсуждения исходники проектов, в разработке которых использовался «ChatGPT (сервис OpenAI)» в качестве языковой модели.

Это история о том, как:

ИИ писал код;

ошибки становились уроками (learning by doing);

скрипт "на коленке" оброс структурой.

Особенность данного материала — в его спонтанности и полученных результатах, так как в процессе ChatGPT выступал то наставником, то «костылём», а где-то и источником новых проблем.

Что вы найдёте под катом:

краткий разбор архитектуры;

немного умозаключений о работе LLM.

Вот так учишь-учишь английский, думаешь, что ты все знаешь и на коне, а потом приходишь в IT-компанию после ВУЗа и осознаёшь, что, по сути, не знала ничего.

Какие открытия я сделала для себя в английском, когда начала делать первые шаги в technical writing и переводах 13 лет назад? Я тогда тщательно фиксировала всё интересное - и делюсь этим списком с вами. Кстати, он будет полезен не только тех. писателям, но и тестировщикам, аналитикам и вообще всем, кто пишет ТЗ, отчёты и test cases.

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

Всем привет!

В этой статье — пошаговый разбор создания сценария использования (Use Case) на основе двух совершенно разных примеров: бронирование отеля в современном IT‑сервисе и покупка брюк на рынке 90-х.

Рассмотрим, как формируются эффективные сценарии использования от этапа создания Use Case диаграммы с помощью промта до детализации сценария.

Привет, Хабр! Меня зовут Катя, я лидирую Gramax, open source-платформу для управления технической документацией.

О Gramax мы писали ранее тут. В этой статье расскажу о Gramax Check — сервисе для автоматических проверок текста на базе LLM. По сути — нашей версии «Главреда», но с настраиваемыми правилами.

«В мои прямые обязанности входит грамотное распределение ресурсов компании, а именно разработчиков 1С и аналитиков 1С в зависимости от их компетенций. Всё чаще в последнее время я слышу фразу: «Я никогда не видел качественное ТЗ». «Как так? Не видели? Давайте я вам покажу! Я пишу ТЗ, за которые не стыдно», — рассказывает моя коллега Татьяна.

При работе с BIM-моделями в формате IFC важно не только управлять геометрией и структурой здания, но и визуальными аспектами — например, цветами элементов. Цвет в IFC используется для улучшения читаемости моделей, визуализации этапов строительства, указания состояний (демонтаж, новое строительство и т.д.) или просто для улучшения презентации.

В этой статье мы разберём, как с помощью библиотеки IfcOpenShell изменить цвет у конкретной стены в IFC-модели. Вы узнаете:
- как устроено цветовое оформление в структуре IFC,
- как найти нужную геометрию элемента и назначить ей новый цвет.

Меня зовут Анна Лапа (Лапа - это моя реальная фамилия), я биотехнолог и юрист по образованию, патентный специалист по признанию. Занимаюсь патентами в сфере фармацевтики, медицины уже более 12 лет.

Эта неделя у Лапы прошла под лозунгом: «Не сотвори себе кумира» — даже если это Ведомство и самая официальная информация.

Почему? Расскажу на примерах:

Запрос на официальную почту в Ведомство

Помогала клиенту продлить патент на промышленный образец (кстати, поздравьте меня с пятилетием работы по подаче промобразцов!). Так как сейчас Роспатент штормит и он ежедневно меняет что-то в своих электронных сервисах, я решила уточнить, как лучше подать Заявление о продлении.

Базовые вещи — неожиданные ловушки

И тут ответ от Консультационного отдела меня удивил.

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

Кто в здравом уме будет это делать? У вас должны быть веские причины, чтобы извернувшись изобрести решение, в котором документация напишет себя сама.

Как совместить порядок классической иерархии и гибкость Zettelkasten в одной базе знаний? Делюсь своим опытом построения эффективной системы заметок в Obsidian для инженеров и IT-специалистов: структура, шаблоны, метаданные, соответствие ITIL и ISO. Если вы хотите, чтобы ваши заметки работали на вас, а не против - эта статья поможет навести порядок и ускорить работу с документацией.

Привет, Хабр! Меня зовут Катя, я лидирую Gramax, open source-платформу для управления технической документацией. Однажды мы с коллегами утонули в хаосе рабочих документов: без версий, без согласований, без истории принятых решений. Это подтолкнуло нас к созданию Gramax — инструмента, который интегрирует документацию в процесс разработки, делая его прозрачным и управляемым.

В этой статье расскажу, как Gramax помогает на каждом этапе разработки ПО. Как перейти к документированию в подходе Docs as Code и шагнуть дальше — к Everything as Code.

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

В статье разберем 7 самых мощных инструментов в арсенале бизнес-аналитика, которые помогут превратить любую задачу в структурированный процесс. Эти техники подобраны не случайно — они идеально дополняют друг друга и позволяют глубже погрузиться в проект.

Диагностика хаоса - первый шаг. Но сама по себе она ничего не меняет. Это лишь осознание проблемы. Настоящая работа начинается на этапе структурирования требований.

Это тот момент, когда вы берёте множество разрозненных данных, противоречий, записей в Telegram, Excel-таблиц, каких-то старых писем и превращаете всё это в рабочий артефакт: чёткий, пригодный к реализации, контролируемый и понятный всем участникам.

Структурирование - это не про красивые документы. Это про построение системы управления требованиями, которая будет жить и развиваться вместе с продуктом. Именно здесь начинается настоящий системный анализ.