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

Сегодня в чате техписателей спросили про разницу между Docs-as-Code и DocOps.

Docs-as-Code — это один из подходов к организации документирования, который рекомендует определенное устройство процессов и диктует выбор инструментов. Звучит сложно? На самом деле строится всё на языке разметки, Гите и SSG.

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

По сути и на практике DocOps — это набор инструментов для автоматизации всех процессов документирования. Инструментов, которые вы используете у себя в компании для подготовки, проверки и публикации документации. Естественно, о Ворде речь не идёт. Естественно, инструментов без процессов не бывает. Но организация документирования это всё-таки задача руководителя, а не докопса.

Кстати. Человек, роль, должность это не DocOps, это DocOps-инженер. Если из контекста можно понять, что речь о человеке, то, конечно, обычно сокращают до «наша докопс сегодня учудила». Но всем должно быть понятно, что учудила не инженерная дисциплина, а коллега.

Премьера nanoCAD BIM Строительство 25: год развития, опыт и новые горизонты

Провели онлайн-презентацию новой версии BIM/ТИМ-решения nanoCAD BIM Строительство 25 в *.dwg-среде для архитекторов и конструкторов.

В VK и RuTube трансляцию посмотрели около тысячи человек. Сегодня выкладываем для вас полезные таймкоды видеопрезентации.

Денис Ожигин, технический директор компании «Нанософт»:

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

С выходом nanoCAD BIM Строительство 25 мы предоставляем проектировщикам еще больше контроля над проектом как в плане создания модели будущего здания, так и в управлении атрибутивной информацией. При этом пользователь остается в привычной *.dwg-среде: от умного копирования элементов по этажам и управления марками в Диспетчере до встроенной проверки на коллизии без необходимости экспорта модели в формат IFC или другие программные продукты. Это не просто обновление версии, а мощный инструмент повышения точности, скорости и качества проектирования зданий и сооружений с применением технологии информационного моделирования».

Важным шагом в развитии nanoCAD BIM Строительство стало появление официальной библиотеки материалов и объектов водосточных систем от компании «ТЕХНОНИКОЛЬ». Полностью интегрированная в библиотеку программного продукта, библиотека «ТЕХНОНИКОЛЬ» включает 82 материала, 48 объектов водосточных систем и кровельных элементов. Среди функциональных особенностей объектов поддержка параметризации (объекты изменяют свою геометрию при изменении соответствующих параметров) и интерактивное взаимодействие (в объектах реализованы «ручки» и точки подключения для упрощения процесса размещения и редактирования)

Смотрите самые интересные темы презентации:

02:54 Развитие интерфейса
04:58 Копирование объектов по этажам
08:13 Режим «Марка» в Диспетчере задач
11:04 Размещение проемов
12:09 2D-представление проемов
12:49 Новая «ручка» управления булевыми операциями
15:17 Проверка на коллизии объектов NBIM
17:39 Работа со сводными моделями
18:20 Единая среда анализа модели
19:05 Экспорт аналитической модели в формат DXF
24:46 Обновление библиотеки объектов
30:41 Интеграция библиотек «ТЕХНОНИКОЛЬ»
32:41 Обновление SDK
33:58 Обновление API
39:17 Полезные ресурсы
40:18 Где скачать nanoCAD BIM Строительство 25?
40:36 Где приобрести nanoCAD BIM Строительство 25?
42:39 Сессия вопросов и ответов

Тестировать nanoCAD BIM Строительство 25 можно прямо сейчас, скачав бесплатную 30-дневную пробную версию на официальном сайте nanocad.ru.

nanoCAD BIM Строительство 25 доступно в трех конфигурациях:

1. конфигурация «nanoCAD BIM Строительство» – для проектирования архитектурной и конструктивной частей зданий/сооружений в *.dwg-среде;

2. конфигурация «nanoCAD BIM Архитектура» – для проектирования архитектурной части зданий/сооружений с применением технологии информационного моделирования в *.dwg-среде;

3. конфигурация «nanoCAD BIM Конструкции» – для проектирования металлических, железобетонных и деревянных конструкций зданий/сооружений в *.dwg-среде.

Цены на nanoCAD BIM Строительство 25

Годовая лицензия

Конфигурация «nanoCAD BIM Строительство»

от 59 800 руб.

Постоянная лицензия

Конфигурация «nanoCAD BIM Строительство»

от 199 300 руб.

Годовая лицензия

Конфигурация «nanoCAD BIM Архитектура»

от 52 000 руб.

Постоянная лицензия

Конфигурация «nanoCAD BIM Архитектура»

от 173 300 руб.

Годовая лицензия

Конфигурация «nanoCAD BIM Конструкции»

от 52 000 руб.

Постоянная лицензия

Конфигурация «nanoCAD BIM Конструкции»

от 173 300 руб.

Действующий прайс-лист представлен на сайте в разделе «Цены».

В предыдущем посте мы рассказали, как мы разработали решение NSR Specification для автоматизации экспертизы цифровых информационных моделей (ЦИМ).

🚆 Сегодня хотим поделиться, как мы смогли проверить работоспособность своих инструментов обработки требований в рамках пилотного проекта с РЖД!

•  Мы очень хотим выпустить универсальный инструмент, который действительно будет работать на практике. Именно поэтому нам важны пилотные проекты, в ходе которых мы дорабатываем свой функционал.

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

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

🔈 Поэтому нам надо показывать и доказывать. Форсировать интерес, создавать спрос. И когда РЖД согласились показать нам свою ЦИМ, чтобы мы смогли попробовать применить наши сценарии проверки, это была фантастическая возможность! Спасибо коллегам!

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

Укрупненный список вызовов:

1️⃣ РЖД использует свой отраслевой классификатор для описания элементов ЦИМ. И он прекрасен, потому что позволяет обеспечить настоящую информационную полноту модели.

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

2️⃣ ЦИМ была передана в формате ifc. А проверки решено было запускать в CADLIB Модель и Архив. Из-за этих факторов мы не смогли использовать некоторые структурные связи элементов.

3️⃣ Требований для пилота было отобрано немного. Всего четыре. Зато каких! Тут тебе и табличный формат, и заковыристые формулировки, и расчетные значения, которые нам надо было преобразовывать в формулы.

4️⃣ Одно из требований устанавливало минимальные расстояния в свету. Специально для таких случаев у CADLIB МиА есть функционал проверки минимального расстояния в плане. А вот у нас в Модуле семантического анализа требований не оказалось нужного инструмента для передачи данной особенности. Пришлось реализовывать!

И вот счастливый финал: мы показываем коллегам из РЖД результаты наших экспериментов...

И слышим в ответ, что мы не учли важный момент:

Нормативное требование устанавливает минимальное расстояние между осями трубопроводов, а CADLIB МиА измеряет расстояние между стенками труб. В самом требовании этот нюанс прямым текстом не озвучен. Но специалисты-то знают!

Нужно пересчитать.

О счастье, у нас получилось и это!
С костылями и молитвами (ибо прямого указания нет), но получилось!

СМОТРИТЕ ВИДЕО: RuTube, VK Видео, YouTube

Было невероятно приятно получить такой комментарий:

Гуменюк Алексей, заместитель начальника Центра компетенций по внедрению ТИМ, «РЖД»:

Когда на первой встрече нам продемонстрировали возможности разрабатываемой системы, мы не поверили своим глазам, это какое-то «шаманство», не иначе. И мы ушли думать какую задачку можно скормить этой машине. Вскоре вернулись с ТЗ, моделями и выдержками из нормативной документации, дополнили устными комментариями, что бы хотелось видеть по итогу. Спустя несколько недель коллеги вернулись с отчетной презентацией… и снова «шаманство», но уже с нашими моделями и под наши задачи.

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

Новая версия Gramax!

Приглашаем вас протестировать экспериментальные функции:

• 💡  Статический сайт в облаке Gramax. Можно опубликовать свою документацию буквально за пару кликов, для этого не нужен сервер или хостинг. Достаточно нажать «Опубликовать в облако» и войти в почтовый аккаунт.

• 💡  Фильтр по содержимому. В каталоге можно создавать статьи и абзацы для разных сборок. На портале для чтения они будут фильтроваться с помощью переключателя. 

• 💡  Браузерная версия на мобильном. Браузерную версию Gramax можно использовать на мобильном телефоне. Доступны все действия, как при работе на компьютере.

А также:

• 📌  Новая главная страница. Улучшили внешний вид главной страницы. Добавили возможность создавать вложенные группы.

• 📌 Транскрипция речи с помощью ИИ. Если в пространстве включены ИИ-функции, редактор может автоматически транскрибировать аудиозаписи в текст.

• 📌 Просмотр изменений после синхронизации. После синхронизации автоматически открывается окно сравнения ревизий: сравнивается новая версия каталога с версией до синхронизации.
  

Об этих и других изменениях читайте в Release Notes 🔥

Как на самом деле нужно понимать ГОСТ. Это не закон, которого нужно строго придерживаться. Это вообще не закон. Это правила, которые соблюдают некоторые игроки индустрии, договорившиеся между собой.

Но лучше бы они хотя бы попытались скосплеить кодекс Хабра: https://habr.com/ru/docs/authors/codex/

Пошаговые инструкции сборки — больше не ад для техписов

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

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

На данный момент мы собрали из исходников документы для 647 конфигураций серверов. Даже при таком сравнительно небольшом количестве инструкций мы простым делением получаем затраты на один документ в размере 2 человеко-часов. Это в 12,5 раз дешевле, чем писать отдельные инструкции вручную — выше мы оценивали затраты такого подхода. В итоге с документацией справляются шесть человек — а если бы мы делали инструкции вручную, потребовалось бы не меньше 13 сотрудников. После внедрения конструктора мы оценили дальнейшие трудозатраты, продолжили работу с динамической документацией, и уже через несколько месяцев система начала окупаться.

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

Как навели порядок в работе техписателей и ускорили процессы

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

Чтобы навести порядок, команда предприняла несколько шагов:

• Ввели единый стиль оформления задач, документов и исходников.

• Определили правила именования файлов, веток и структуру репозитория.

• Согласовали формат взаимодействия внутри команды.

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

Стали шире использовать возможности разметки: избавились от лишнего, ввели переиспользование через ключи (conkeyref, keyref) и упростили поддержку кода. Поработали и с визуальной частью:

• Ввели правила для изображений: фиксированные размеры, формат, плотность.

• Стандартизировали визуальный стиль.

• Убрали визуальный шум, сфокусировались на главном.

• Установили лимит на размер изображений для ускорения загрузки.

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

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

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

Саботируйте процесс накопления знаний и документирования, чтобы вас ни в коем случае не могли уволить!

Ну ладно, это кликбейт 😅

В подкасте «Техкомпод» поболтали с Вовой о процессах, менеджменте знаний, структурировании документации и Gramax. Предлагаем вам тоже послушать и присоединиться к обсуждению!

• Расшифровка выпуска

• Яндекс Музыка

• Apple Podcasts

Новая версия Gramax!

• Сравнение ревизий. Можно сравнить текущую версию каталога с одной из предыдущих.

• Экспорт в корпоративных шаблонах DOCX. Добавили возможность загрузить корпоративный шаблон DOCX и экспортировать статьи и каталоги в этом шаблоне.

• Избранное. Каталоги и статьи можно пометить как Избранные для быстрой навигации. Это доступно как в приложении, так и на портале документации.

• Связанные статьи. В меню статьи можно просмотреть: куда ссылается статья и какие статьи ссылаются на нее.

Об этих и других изменениях читайте в Release Notes 🔥

Думаю, технический писатель по характеру — ремесленник. В том смысле, что любит продукт делать сам, своими руками. А документация всегда продукт осязаемый, постоянно радующий нас, ремесленников, конкретными результатами. Сели, написали один абзац — и уже стало хорошо! Не надо ждать два года до MVP.

Если вам стало интересно, какие у ремесленников харды и софты. Читайте дальше!

На мой взгляд, у джуна и мидла харды такие:

1. Умение хорошо писать инструкции, любые.

2. Умение пользоваться тем, о чём пишешь.

3. Умение пользоваться инструментами, в которых тебе приходится писать.

У синьоров харды немножечко другие. Очень зависит от компании. Тут может быть управление процессом и командой, и стайлгайды, и докопсинг, и метрики с бюджетами. А может быть синьор просто умный и очень круто разбирается в IP-сетях.

Но вернёмся к джунам с мидлами. Умение общаться я отношу к софтам. Желание самостоятельно разбираться в сложной области гораздо важнее умения общаться. Если вы, такой общительный, постоянно будете дёргать всех, чтобы вам объяснили-показали, и при этом полученное знание не будет оседать в вас и приумножаться в доке. Вы просто разочаруете команду. И в конце концов вас сошлют в (бухгалтерию) менеджеры.

Как подход Docs-as-a-code применили в создании документации для TestY TMS

Команда разработки системы управления тестами TestY объединилась с командой технических писателей, чтобы создать удобную документацию.

Для ведения документации выбрали подход Docs-as-a-code. Документация хранится вместе с кодом приложения. Для написания и сборки использовали более-менее классическое сочетание: rST-формат в связке со Sphinx. 

Инженеры уверены, что такой вариант предоставляет большую гибкость, чем стандартный MD. К тому же,  rST в связке со Sphinx — стандарт документации для open source-проектов.

Разработчики поддерживают документацию в актуальном состоянии, поэтому рассчитывают, что в дальнейшем любое изменение текущей функциональности, как и разработка новой, будет сопровождаться обновлением документации. Это будет одним из Definition of Done для реализации фич.

Помимо документации в релизе 2.1 появилась темная тема и другие обновления интерфейса. Читайте о них в статье →

Pull/Merge Request для согласования требований и документации

Аналитики и технические писатели, признайтесь: сколько раз вы теряли время, сравнивая версии документов в MS Word? Компьютер тормозит, красные и синие правки сливаются в кашу, а поиск согласования в бесконечной переписке или Confluence превращается в квест.

Есть решение — берем механизм Pull/Merge Request и применяем его к текстам! Что получаем:

• Все правки в одном месте. Редактируйте несколько документов сразу и смотрите изменения в едином окне. Забудьте про переключение между файлами и версиями!

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

• Простое согласование. Назначайте проверяющих и получайте их апрувы прямо в интерфейсе. Никаких "ок" в письмах или мессенджерах!

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

• Экономия времени. Gramax объединяет редактирование, ревью и согласование в одном месте — больше не нужно жонглировать Word, Confluence и почтой.

И все это в Gramax! Как всегда: бесплатно и с открытым исходным кодом.
Все как в коде, только проще.

💥 Майская версия Gramax 💥

Что нового мы добавили в open source-платформу для управления технической документацией Gramax.

• ИИ-поиск для портала документации. Раньше поиск по документации был ограничен точным совпадением слов, теперь можно подключить ИИ-поиск от любого провайдера (например, OpenAI, Anthropic и др.) и искать по смыслу. Даже при неточном запросе пользователь получит релевантные результаты. Поддерживается как облачное подключение, так и запуск собственного сервера — для тех, кому важна приватность.

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

• Шаблоны. Добавили возможность создавать шаблоны со свойствами и использовать их в статьях. 

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

• Расширенный редактор сниппетов. Теперь сниппеты можно оформлять как и обычную статью без ограничений. 

• Выбор формата для исходных файлов. Добавили 2 дополнительных формата хранения статей — XML и GitHub Flavored Markdown. Изменить формат можно в настройках каталога.

• Вход для внешних пользователей в Gramax Enterprise Server. Добавили возможность настроить вход на портал для чтения по почте: таким читателям не нужно иметь учетную запись в SSO. Достаточно указать свою почту при входе и ввести одноразовый код.

О других изменениях читайте в статье — https://gram.ax/resources/docs/whats-new

PlantUML | Шаблон для описания таблиц БД

Делюсь с Вами разработанным мною шаблоном, для описания таблицы БД в PlantUML, c элементами автоматизации, описание которых указанно в комментариях.

Всем привет!
Делюсь с Вами разработанным мною шаблоном, для описания таблицы БД в PlantUML, c элементами автоматизации, описание которых указанно в комментариях.

Протестировать можете тут, а сам код шаблона указан ниже:

 ' Шаблон описания таблицы БД (в PlantUML)
@startuml

skinparam {
' Параметры для управления нижним колонтитулом
    FooterFontColor #blue
    FooterFontSize 12
' Параметры для управления легендой
    LegendBackgroundColor #lightblue
    LegendBorderThickness 0
}

' Переменные для ускорения описания таблицы
' - PRIMARY KEY можно указывать как: "$PK"
    !$PK="  <size:11><#DarkKhaki:key:></size> (PK)  "
' - FOREIGN KEY можно указывать как: "$FK"
    !$FK="  <size:11><#DeepPink:key:></size> (FK)  "
' - NOT NULL (N-N) можно указывать как: "$NN"
    !$NN="  <#LightGreen> **N-N**  "
' - NULL можно указывать как: "$N"
    !$N = "  <#LightCoral> **NULL**  "


' Переменные для ускорения добавления информации о таблице
' - Наименование таблицы БД (латинское)  
    !$table_name="Наимнование_таблицы_БД"
' - Краткое описание таблицы (на русском) 
    !$description="Краткое описание таблицы (на русском)"
' - Ссылка на описание таблицы (на русском)
    !$doc_url="Ссылка"

' Контакты, отображаемые в нижнем колонтитуле
    !$autor ="Зимин Антон"
    !$email ="antzim_in@ya.ru"
    !$telegram="antzim_in"

' Заголовок документа, формируется автоматически из заполненных выше параметров (при необходимости можно удалить)
    title $table_name | $description

' Легенда (может быть заполнена любыми необходимыми данными)
' - "right" говорит о том, что легенда будет расположена справа 
legend right
**Легенда:**
| Версия документа: | 1.0.0 |
end legend



' Описание таблицы
' - заголовок таблицы, с кликабельной ссылкой (если выгружать в SVG) формируется автоматически
class "[[$doc_url $table_name]] ($description)" as $table_name << (T,#FF5722) >>{

|=   PK,FK  |=   Поле   |=   Тип   |=   Обязательность   |=   Значение\n по умолчанию   |=   Описание   |
| $PK | id | serial | $NN | | Идентификатор записи в таблице |
| $FK | subscriber_id | integer | $NN | | Идентификатор записи в таблице subscriber |
|     | electronic_address | varchar(255) | $N | | Электронный адрес \n клиента |
|     | created_at | timestampz | $NN | now() | Дата и время создания записи в БД |
|     | updated_at | timestampz | $NN | now() | Дата и время обновления записи в БД |
}

' Нижний колонтитул (формируется автоматически из введенных параметров)
footer © $autor | tg: [[https://t.me/$telegram @$telegram]] | email: $email
@enduml

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

Всем спасибо.
----

Пообщаться со мной можно в telegram: @antzim_in
P.S. Также, если Вам интересно, я веду telegram канал @sa_chulan и буду очень рад Вашей подписке.

Тестирование документации: залог успешной разработки

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

Почему важно проверять документацию заранее?

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

Проверка требований до начала разработки помогает находить проблемы раньше, чем они превратятся в баги. Чем раньше найдёшь ошибку, тем меньше потом придётся исправлять. Это называется "Shift-Left Testing", что по сути означает — тестировать раньше, чтобы потом не было больно.

Вот какие проблемы можно найти на этом этапе:

• Противоречия в требованиях: например, в одном месте написано "сохранить данные", а в другом — "удалить данные". Так какой из них правильный?

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

• Отсутствие важных условий: что-то важное просто забыли описать, и программа не знает, что с этим делать.

• Ошибки в сценариях использования: не описаны крайние случаи, например, что делать, если пользователь ввёл неправильные данные.

Как можно тестировать требования?

Есть несколько способов проверить, что в документации нет ошибок:

• Формальная проверка: использование строгих правил, чтобы убедиться, что всё написано правильно.

• Чтение и обсуждение: собираемся, читаем вместе, обсуждаем и находим проблемы.

• Моделирование: создаём простые схемы, чтобы понять, как всё должно работать.

• Анализ текста с помощью ИИ: современные программы могут сами искать ошибки в тексте требований.

Что будет дальше?

Ниже можете видеть видео, где видно, как наш инструмент TestWriter проводит проверку документации с помощью ИИ. Это пока что прототип, но уже видно, как много ошибок можно найти ещё до начала разработки.

Полезные материалы по теме:

• Тестирование требований — Teamlead Roadmap: Простое объяснение, зачем проверять требования перед началом разработки.

• Критерии качества требований с примерами — Habr: Примеры, как сделать документацию понятной и понятной для всех.

• Тестовая документация: что учитывать при постановке эффективного процесса тестирования — Habr: Как правильно описывать требования, чтобы не возникало путаницы.

• Роль формализации требований в тестировании программного обеспечения — КиберЛенинка: Почему важно прописывать требования максимально чётко.

• Тестирование требований — Особенности — Quality Lab: Как работают с требованиями на практике и какие ошибки бывают.

P.S.: а вот ссылка на мой блог в Telegram: https://t.me/it_vadimqa

Шаблон записи о принятии архитектурного решения

# Идентификатор и заговолок

Утверждение о принятом решении.

# Статус

Черновик\Утверждено\Заменено на ADR-XXX

# Контекст

Почему решение необходимо. Предположения, ограничения, мотиваторы принятия решения.

# Критерий оценки

Какие приоритеты в принятии решения? Какие из параметров и характеристик системы рассматриваются или используются в принятии этого решения. Какие мотиваторы и ограничения использовались при принятии решения?

# Доступные варианты

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

# Решение

Сделанный выбор и аргументация в его пользу.

# Последствия

Положительные и отрицательные последствия принятого решения.

# Консультации

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

Простой, быстрый и бесплатный тест на профориентацию.

1. Кто вызывает у вас зависть? Почему? Что он—она делает? Что именно вас впечатляет в результатах?

2. Что это за роль в экономике: сотрудник в найме, учёный на грантах, волонтёр или вообще целый бизнес?

3. Когда вы почувствовали укол зависти, в каком контексте находился ваш предмет зависти? Выступал на конференции или что-то ещё? Сколько процентов от общего времени занимает эта активность, как думаете?

4. Если выяснится, что для результата, который вызвал у вас зависть, нужно много работать и 80% времени делать рутинные, неинтересные вещи, ваша зависть уменьшится или не сильно?

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

Инфостиль разрешает вам писать просто и ясно. И не поощряет вас делать вид, что вы умнее, чем вы есть на самом деле.

Всё. Больше инфостиль ни в чём не виноват. Все проблемы, все неудачи — из-за вас, а не из-за инфостиля.

Привет! Сегодня мы хотим представить программу для контрибьюторов Diplodoc — опенсорс-платформы Яндекса для создания документации в формате Docs as Code. Это ваш шанс внести значимый вклад в развитие платформы и получить классные призы за участие.

Мы предлагаем

Мы создали специальную подборку задач, которые вы можете решать, чтобы помочь нам улучшить платформу. Задачи доступны на разных уровнях сложности: easy, medium и hard. Это отличная возможность проявить себя, внести свой вклад в проект и получить заслуженные награды.

Вы получаете

За решение лёгких и средних задач мы подготовили стильный мерч Diplodoc. А за сложные задачи вы вдобавок получите промокод на использование ресурсов Yandex Cloud.

FAQ

Как выбрать задачу?

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

Как отправить решение?

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

Сколько задачек можно решить?

Сколько угодно, однако приз вы получите только за одно решение.

До какого числа действует программа?

Программа активна до конца января. Мы будем добавлять задачи, так что следите за обновлениями в нашем чате в Telegram!

Не упустите возможность внести свой вклад в будущее Diplodoc!

Используем PlantUML не по назначению: рисуем маппинг данных с помощью диаграммы класса

Когда у вас docs as code, хочется, чтобы все было прямо по «докс экс кодовски», в частности, чтобы диаграммы и схемы тоже рисовались кодом.

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

Вот так выглядит код (если нужны пояснения, обращайтесь):

@startuml

hide circle
left to right direction

class Structure_1 {
  field_1
  --
  field_2
  --
  field_3
}

class Structure_2 {
  field_1
  --
  field_2
  --
  field_3
}

package transform <<Rectangle>> #yellow {
  
}

package "addition data" <<Rectangle>> #purple {
  
}

package "data transform" <<Rectangle>> #blue {
  
}

Structure_1::1 -down[#white]-> transform
Structure_1::1 -down-> transform
Structure_1::1 -down[#white]-> transform

transform -down-> Structure_2::1

Structure_1::2 -> Structure_2::2

Structure_1::3 -down-> "data transform"

"data transform" -down-> Structure_2::3

"addition data" -down-> 

А так — результат (маппинг данных):

Какие нюансы нужно учесть:

1. Активно «играйте» связями: они помогают двигать объекты на диаграмме.

2. Используйте невидимые элементы и связи.

Сначала это кажется сложно. Но позже, когда освоишь ухищрения и «костыли», рисовать настоящие шедевры. И тогда у час будет полнейший docs as code.

Похожее можно рисовать и в graphviz, но там синтаксис потяжелее будет. Как? Могу показать.