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

Научимся превращать бизнес-требования в рабочую схему БД и документировать ключевые решения! Без недопонимания, технического долга и смс.

Представьте, что вы разработали программное обеспечение. Все идеально: код отточен, тесты пройдены, система готова к работе. Но тут встает вопрос: как отправить документацию заказчику?

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

Какие бывают схемы

Это история о том, как я устал держать в голове инфраструктуру по всем своим проектам.

Прод падает — а ты тратишь время на то чтобы вспомнить где лежит Grafana, где настраивается DNS, чей Docker Registry мы используем, есть ли у нас CDN и какой.

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

На этом Google IO google показал новый инструмент разработки - https://jules.google.com

В чем плюсы: пока бесплатный, работает на gemini, и это AI Agent.

Что это значит (пример):
Часто бывает проблема, что кол-во модулей в проекте или библиотек которые хотелось бы сделать, превышает кол-во которое можно поддерживать. Особенно если ведешь open source библиотеку.

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

Чтобы начать, обычно можно использовать небольшой промпт чтобы предсоздать план по которому Jules будет частично следовать (на самом деле она пересоздаст план, но имея рефренсы ей будет проще):

Всем привет! Меня зовут Катя, я развиваю 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 лет.

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

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

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

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

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

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