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

Привет, Хабр! Я Александр Зырянов, проектный менеджер 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-таблиц, каких-то старых писем и превращаете всё это в рабочий артефакт: чёткий, пригодный к реализации, контролируемый и понятный всем участникам.

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

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

К сожалению, так бывает! И попытки сразу перейти к структурированию в текущих условиях - очень большая ошибка. Потому что без предварительной оценки есть огромный риск потратить большое количество времени на “работу в стол”.

Короткий ответ — потому что чаще всего их невозможно читать.

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

Есть два типа системных аналитиков: те, кто на слова "Acceptance Criteria" кивают уверенно, и те, кто кивают с лицом человека, которому эти слова не приносит радости. А потом открываешь их спецификацию и понимаешь, что критерии приёмки там формулировал кто угодно, но только не человек, который собирается это реализовывать.

Если ты читал мою прошлую статью на Хабре про Gherkin, то уже знаешь, что синтаксис GWT - это не просто красивый способ писать тесты. Это способ фиксировать поведение системы в формате, который понятен и бизнесу, и тестированию и разработчику.