Владимир Бурмистров
Главный системный аналитик в IT-холдинге
Рубрика «документирование»
Топ инструментов ИИ для системного аналитика
2026-01-13 в 14:41, admin, рубрики: документирование, ИИ, ии-ассистент, Инструменты ИИ, искусственный интеллект, продуктивность, системный аналитик, экономия времени, эффективность
От хаоса к ясности: почему форма требований определяет успех проекта
2025-12-16 в 12:15, admin, рубрики: документирование, критерии качества, управление требованиямиАналитик может глубоко погрузиться в предметную область, грамотно применить паттерны проектирования и качественно подготовить артефакты. Но блестящее содержание тонет в хаосе, если у требований нет безупречной формы. Путаница в артефактах, неясность приоритетов и источников — прямая дорога к потерянным человеко-часам. Именно поэтому четкая форма и продуманная структура требований не менее важна, чем их содержание.
Какими должны быть требования
Прежде всего требования — это описания свойств и поведения системы. Вкратце именно так определяет это понятие Карл ВигерсЧитать полностью »
Документирование API в Java приложении с помощью Swagger и OpenAPI 3.0
2021-01-07 в 14:37, admin, рубрики: api, java, rest, spring, swagger, документированиеВеб-приложение часто содержит API для взаимодействия с ним. Документирование API позволит клиентам быстрее понять, как использовать ваши сервисы. Если API закрыт от внешнего мира, то все равно стоит уделить время спецификации — это поможет вашим новым коллегам быстрее разобраться с системой.
Создание документации вручную — утомительный процесс. Swagger поможет вам упростить эту работу.
Как сделать так, чтобы вашу статью или документацию поняли быстро и точно
2020-03-14 в 23:30, admin, рубрики: восприятие информации, документирование, информационный стиль, мозг, Научно-популярное, советы и рекомендацииНе только содержание, но и структура текста должна быть осмысленна.
Так, если мы говорим о техническом или научном тексте, например, о статье или документации, то форма должна помочь максимально быстро и легко понять содержание. Для меня, в случае статьи, это значит, что структура должна быть приблизительно такой:
- Заголовок
- Суть статьи
На основе этих нескольких предложений вместе с заголовком читатель должен понять, интересно ли ему читать эту статью дальше. - Краткое изложение
Здесь в максимально сжатом виде, тезисно, но с необходимой точностью и полнотой должна быть отражена суть данной статьи — от нескольких предложений до нескольких страниц. Кому-то, кто глубоко в теме этого может быть достаточно для понимания всей статьи. Но в любом случае читателю полезно представлять в самом общем виде, о чем эта статья, и какие выводы он получит в конце. - Логика статьи
Если статья длинная, содержит много разделов и сложную логику, то эта глава может быть также полезной. По сути это расширенное оглавление. Здесь кратко, на одной-двух страничках, излагается логика рассуждения, сухо, без деталей. Опять-таки, кому-то этого будет достаточно для того, чтобы все понять. Если сложно, то читатель может это пропустить (как оглавление) и читать дальше. - Упрощенное изложение
Если статья достаточно сложная, то многим было бы удобно сначала понять концептуально, что же хочет сказать автор. Поэтому неплохо сначала изложить все так, как если бы вы рассказывали студентам, упуская сложные доказательства, и, возможно, не столь формальным и строгим языком. Для очень многих такой уровень изложения может быть достаточным, и они остановятся здесь. - Строгое изложение
Здесь строго профессиональное изложение.
ProКонтент 2019: три хардовых доклада и частушка
2019-04-17 в 14:17, admin, рубрики: Блог компании «Лаборатория Касперского», документирование, конференции, нейросети, юзабилити интерфейсовПривет! У нас прошла конференция по разработке технической документации – ProКонтент 2019. Мне довелось изнутри посмотреть на процесс рождения конференции и даже выступить с пятиминутным мини-докладом. Не претендуя на объективность, очень кратко расскажу про доклады, которые мне больше всего понравились.
Читать полностью »
Семантическая разметка: LaTeX, DocBook или ???
2017-10-05 в 15:20, admin, рубрики: asciidoc, docbook, doconce, latex, markdown, open source, XML, xslt, документирование, Семантика, семантическая разметкаПисал комментарий к статье и понял, что надо выносить в отдельный пост.
Как многие отмечают там в комментариях статья отстой, человек не разбирается и смешал всё в кучу, попробую поделиться своими выводами от использования разных разметок.
Читать полностью »
Log in или Log on? Front-end или Frontend? Продолжаем разбираться
2016-11-14 в 6:09, admin, рубрики: IT-стандарты, английский язык, документирование, Разработка веб-сайтов, разработка мобильных приложений, технический писатель
В прошлый раз мы говорили о разнице между login и log in. В продолжение темы — ещё несколько нюансов, о которых вы просили рассказать в комментариях.
Login или Log in?
2016-10-27 в 13:24, admin, рубрики: IT-стандарты, английский язык, документирование, Разработка веб-сайтов, разработка мобильных приложений, технический писатель
‘Login’ или ‘log in’? Одно слово или два? Это достаточно распространенный вопрос среди тех, кто пишет на английском языке. Давайте разберемся, как же правильно.
RAML 1.0: обзор нововведений
2016-04-07 в 13:30, admin, рубрики: api, RAML, RAML 1.0, selectel, Блог компании Селектел, документирование, селектел, метки: RAML, RAML 1.0 
О RAML — языке разметки, используемом для описания RESTful API, мы уже писали. В обсуждении статьи на Хабрахабре один из читателей заметил, что RAML уже давно не обновляется, чуть ли не с лета 2014 года.
Несколько месяцев формат RAML был существенно усовершенствован. Новая спецификация версии 1.0 была опубликована на официальном сайте относительно недавно, в начале октября 2015 года. По сравнению с предыдущей версией (0.8) в неё было внесено много изменений и дополнений. О наиболее значительных нововведениях мы подробно расскажем в этой статье.
Читать полностью »
Автоматизация оформления документации
2016-03-30 в 10:44, admin, рубрики: csv, ERP-системы, jinja2, latex, python, XML, визуализация данных, документация, документированиеРаботая над проектами связанными с авионикой мне потребовалось оформить несколько комплектов документации с полным описанием проекта. Также следовало учитывать требования многих ГОСТов на оформление и на содержание документации, таких как ЕСПД, КТ-178B и других.
Описание должно было в себя включать:
- Планы разработки ПО
- Требования к ПО
- Описание реализации требований к ПО
- Таблицы трассируемости(соответствия) требований к ПО и реализации
- Описание тестов на ПО (Примеры и процедуры верификации ПО)
- Таблицы трассируемости(соответствия) требований к ПО и тестов
- Отчет об обнаруженных проблемах
- Указатель конфигурации(описание версии ПО и совместимости со сторонним ПО и оборудованием)
Объем документирования очень большой. Данные во всех документах связаны друг с другом, поэтому при изменении проекта (например добавления нового требования), приходится редактировать практически все документы. Плюс к этому можно где-то ошибиться или забыть поправить, что приводит к ошибкам в документации.
Далее в статье я расскажу как я решил эту проблему.