Системный аналитик
29-30 ноября прошла конференция для аналитиков FlowConf 2022. Основная особенность конференции — ее ориентация на конкретные практические рецепты. Одним из направлений, которое содержит много таких рецептов, стал Docs As Code или, в более широком смысле, DocOps в работе аналитика. В посте представляю обзор этого направления.
Несколько раз мне приходилось выступать в роли архитектора на проектах по созданию информационных систем с большим количеством заинтересованных участников — стейкхолдеров. Могу сказать, работа эта не из лёгких: пока соберёшь под сотню необходимых виз — весь взмокнешь. В этом очерке хочу рассказать о подходах, которые, на мой взгляд, могут облегчить жизнь архитектору и команде проекта.
Продолжая тему использования Asciidoc (и других аналогичных форматов) для организации процессов непрерывного документирования, хочу рассмотреть тему автоматический генерации технической документации.
Автоматическая генерация документации — распространенный, но очень расплывчатый термин. Я понимаю под этим термином извлечение для представления в удобном виде информации, содержащейся в исходном коде и настройках документируемой программы (информационной системы).
В этой статье хочу рассмотреть возможности Asciidoc в части обеспечения требований соответствия документов требованиям единой системы конструкторской документации (ЕСКД), конкретно ГОСТ Р 2.105—9 (далее ГОСТ ЕСКД). Почему именно Asciidoc, я писал здесь.
Сразу уточню. Вопрос форматирования документа здесь не рассматривается. Создающий документацию не должен задумываться о форматировании. Как системный аналитик я создаю содержание и контролирую его структуру. Для получения документа, соответствующего ГОСТ ЕСКД или другому аналогичному стандарту, я должен нажать кнопку и получить корректно отформатированный документ в любых требуемых вариантах: pdf, Open Document (Libre
Office/Open Office), Open XML (Microsoft Word) и прочих.
После работы над https://github.com/CourseOrchestra/asciidoctor-open-document уверен,
что все проблемы форматирования решаются адекватными усилиями.
Рассмотрим структуру документа Asciidoc, соответствующего требованиям
ГОСТ ЕСКД.
Ключевым фактором для по-настоящему массового продукта является простота использования, функциональность и стоимость. Как принципиальный сторонник бесплатного ПО я являюсь давним пользователем технологии АsciiDoc и считаю, что на сегодняшний день она располагает самым большим потенциалом.
Функциональность Markdown и даже reStructuredText ограничена, а порог входа для DocBook и DITA достаточно высок, чтобы поставить на них крест как на массовом продукте. Нужна золотая середина между функциональностью и простотой. Система документации должна быть одинаково удобна на всех этапах жизненного цикла программного продукта: проектирование, реализация, сопровождение. В идеале она должна прекрасно применяться и вне задач создания программных продуктов.
Основной проблемой, с которой я сталкивался при подготовке документации в АsciiDoc – это отсутствие полноценного конвертера в docx (MS Word) или odt (OpenOffice/LibreOffice) для сдачи документации заказчику в этих его любимых форматах. Также эти форматы очень удобны для сравнения выходных документов.
Это небольшая заметка посвящена теме оформления результатов создания ИТ-продуктов для органов государственной власти и крупных корпораций. В настоящее время при сдаче работ указанным организациям требуется представить десятки документов (часто в бумажной форме), подтверждающих соответствие выполненных работ требованиям технического задания.
Вопрос заключается в том, обеспечивает ли такое количество документации надлежащее качество выполненных работ?
Для тех, кто в теме, давно уже не секрет, что громадное количество «макулатуры», сдаваемой заказчику, часто служит прикрытием творческой несостоятельности заказчика или разработчика, которые не могут правильно поставить задачу и сделать качественный продукт и прикрывают это объёмом технической документации. «Макулатура» также служит обоснованием завышенной стоимости программного продукта.
Чиновника это устраивает, так как при любой проверке можно показать объём странице-километров документации и избежать ответственности за неработающее программное обеспечение.
В заголовке использовано слово сложной, под которым можно понимать все, что угодно. Утверждение о том, что 2 * 2 = 4, если вдуматься, тоже очень не просто. Но в данном случае всё банальнее. Речь идёт о ЕСКД, ГОСТ, ОСТ и тому подобных скучных терминах, отягчаемых бюрократической процедурой согласования.
Года полтора назад мы втянулись в проект по разработке небольшой отраслевой информационной системы. По этой небольшой системе необходимо было разработать с полсотни взаимоувязанных документов и согласовать их не меньше, чем с сотней человек.
Сразу решили, что попробуем сделать документацию актуальной, т.е. обойтись без покраски травы в зелёный цвет. И сразу решили, что это будет Asciidoc. Почему? Потому что из текстовых языков разметки для подготовки документации он наиболее функциональный, а разворачивать неповоротливые DITA и Docbook не хотелось.
Пройдя определённую боль, мы с коллегами решили ей поделиться.
Я — системный аналитик, и моя работа заключается в том, чтобы проектировать автоматизированные информационные системы. Впрочем, нет, она заключается в том, чтобы писать и писать документы. Третий раз слово «писать» повторять не буду — все-таки, не «Илиада». Но занудность формы чем-то определенно роднит проектную документацию с древнегреческой поэмой, особенно если речь идет о работе с государственным заказчиком.
Диаграммы — глоток творчества в этом море текста. О диаграммах и пойдет речь в данной статье. Если точнее — о PlantUML — с моей точки зрения, наиболее адекватном инструменте их создания на текущий момент.
