В этой статье мне хотелось бы порассуждать о такой области ИТ-бизнеса, как документирование ИТ-продуктов – автоматизированных/информационных систем (АС, ИС, АИС и т.п.), а также о том, как применение стандартов отражается на качестве разрабатываемой документации и её восприятии целевой аудиторией читателей.

Ни один хороший (т.е. качественный – как в части организации процесса, так и в части ожидаемого результата) проект по созданию (и внедрению) ИТ-продукта не может обойтись без создания документации. Документация позволяет формализовать и зафиксировать различные аспекты, касающиеся ИТ-проекта и создаваемого в его рамках продукта.

Но при этом неизбежно возникает вопрос – а как создать эту документацию?

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

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

Но есть ряд заказчиков (чаще всего это госзаказчики), которые вспоминают, что есть на тему оформления документации государственные стандарты – ГОСТ. И требуют строгого соблюдения этих стандартов.

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

Да, так-то оно так, НО...

Давайте сначала посмотрим на эти стандарты. Что они стандартизуют, когда они были разработаны, когда, кем и при каких обстоятельствах актуализированы (если актуализированы вообще)?

Поскольку речь сейчас об ИТ, не будем смотреть остальные отрасли. Остановимся только на том, что касается информационных технологий.

Итак, какие стандарты в области документирования касаются отрасли ИТ?

Прежде всего, это две серии ГОСТ – 34.х и 19.х.

ГОСТ 34.х

34-я серия – «Информационные технологии. Комплекс стандартов на автоматизированные системы» (сокращённо – КСАС). Из основных в этой серии – это ГОСТ 34.201-2020 «Виды, комплектность и обозначение документов при создании автоматизированных систем» (введён с 2021 года взамен аналогичного от 1989 года), ГОСТ Р 59795–2021 «Автоматизированные системы. Требования к содержанию документов» (введён взамен РД 50-34.698-90, хотя и заявлено, что «введён впервые», но мы‑то знаем...). Сюда же можно и стандарт по испытаниям — ГОСТ Р 59792–2021 (бывший ГОСТ 34.603-92, хотя новый стандарт своё родство с предшественником почему‑то тоже старательно скрывает).

Как видим, вполне себе актуальные стандарты. Но... (снова это «но» - дьявол, как известно, кроется в деталях). Скажем мягко – авторы «римейков» подошли к работе несколько... хм... странно. Стандарты исходные были разработаны более 30 лет назад (а, зная реалии советской бюрократии, можно фактический возраст этих стандартов смело поднимать и до 40). Многое в области ИТ тогда отличалось от современного. Хотя какие-то универсальные вещи и сохранились, но многое поменялось.

Например, в новых стандартах почему-то никак не отражена клиент-серверная архитектура, многозвенная архитектура, распределённые вычисления, кластеризация, виртуализация и т.п. GUI, UX/UI – нет, только«эргономика и техническая эстетика» (а интерфейсов нет, увы).  В качестве описания алгоритма разрешены только Р-схемы и блок-схемы алгоритмов, хотя в нынешних реалиях автоматизации деловых функций и бизнес-процессов просто грех не использовать более удобные и универсальные нотации – IDEF, VAD, eEPC, BPMN. Для чисто ИТ-шных решений удобно использовать UML. Но советские ГОСТы 30+ лет назад этого не знали (оно и понятно – большинства этих нотаций либо ещё не было, либо они были откровенно «вражескими» и «идеологически чуждыми», как SADT/IDEF). Но почему же современные ГОСТы в области документирования ИС не знают до сих пор эти нотации. Стабильность?

ГОСТ 19.х

А что с упомянутой серией ГОСТ 19.х, которая ЕСПД (Единая Система Программной Документации)? О, там всё ещё интересней. Эти стандарты ещё Брежнева помнят – ведь большинство из них выпущены ещё в конце 1970-х и начале 1980-х. Конечно, есть там что-то, что можно считать неизменным и вечным, но всё же отрасль не стоит на месте, развивается, но увы.

Например, как выше уже упоминалось, алгоритм и процесс можно описывать только по ГОСТ 19.701-90 «Схемы алгоритмов, программ, данных и систем. Условные обозначения и правила выполнения». А современные нотации там не отражены.

А вот что в рамках этой схемы допускается:

ЕСКД

А что же от нас в документировании требует ГОСТ в части оформления? О, а тут вообще всё... интересно.

Нам в области ИТ предписывается ориентироваться на... ЕСКД – Единую Систему Конструкторской Документации. Ту самую, что для строительства и машиностроения.

И тут начинается... Нет, не магия.

Не будем лукавить, доблестная компания Microsoft подсадила весь мир, и нашу страну тоже, на свои продукты. В т.ч. на Word. Даже его аналоги из других пакетов офисных программ во многом копируют и интерфейс, и стилевые решения Word. И ничего в этом, в общем-то, плохого – «привычка свыше нам дана (замена счастию она)». Все привыкли к возможностям этих текстовых процессоров, в т.ч. и к стилям. Но...

Но ЕСКД думает иначе. Не буду расписывать все «прелести», кому интересно, сами посмотрите ГОСТ 2.105-2019. Скажу просто – не всегда удобно, и не всегда возможно выполнить все требования этого стандарта (мягко говоря).

Но откуда он взялся, когда, зачем, почему?

А взялся он давно, много десятилетий назад. Когда из всей автоматизации подготовки документов были максимум печатные машинки, имевшие только один шрифт (а до поры и сокращённый набор символов – например, отдельная цифра«0» отсутствовала, совмещаясь с буквой «О», твёрдый знак не всегда присутствовал, совмещаясь с апострофом, и т.д.). И уж понятно, что оформление заголовков, абзацев, списков, таблиц, подписей к рисункам (рисунки тогда, понятно, делались отдельно, вручную) единственным доступным шрифтом можно было сделать только за счёт отступов, прогонов строки, подчерков и т.п.

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

Но вот появились текстовые процессоры WYSIWYG (What You See Is What You Get,«Что видишь (на экране), то и получишь в итоге (на печати)»). Различные гарнитуры шрифтов, цвет, стиль, начертание, размер. Маркеры для списков. И т.п.

Но – нет! Шаг влево, шаг вправо – и да возрадуется нормоконтроль своей новой жертве!

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

Спрашивается, почему? Главное – на что она влияет? На понимание текста? На удобство восприятия?

А списки? Больше двух уровней «низзяяяяя», да и те оформляются криво.

Но дальше – больше. Рамка. Основная надпись.

А кто сейчас вспомнит, для чего была рамка? А ответ-то простой – для того, чтобы явно обозначить край чертежа/документа, чтобы при повреждении листа внутри рамки можно было говорить о необходимости замены экземпляра.

А посмотрим на рамку. Что мы видим? «Копировал», «Проверил». Кто знает, что это? О, это тема интересная.

Как копировали документы в доксероксные времена? Был такой процесс – «синькование» (в честь цианотипии, позже заменённой такой же по технологии, но иной по реактивам «диазотипией»). В чём суть? С чертежа или документа на кальку переносилось всё – линии, точки, буквы, цифры, знаки. Калька, если кто не знает – специальная полупрозрачная бумага. Потом эта калька с нанесённым на ней рисунком – копией оригинала – накладывалась на лист бумаги, покрытый специальным реактивом, засвечивалась, бумага проявлялась, и появлялось изображение – копия исходного чертежа или документа. И лишь в 1960-е появились фотокопировальные аппараты, аналогичные по принципу работы копиру, на Руси именуемому ставшим нарицательным именем«ксерокс».

Так вот, «Копировал» и «Проверил» относилось... К КАЛЬКЕ в процессе копирования документов методом цианотипии/диазотипии. Актуальненько, не правда ли? Особенно для преимущественно«машинных» (т.е. сделанных с помощью текстового процессора и иного необходимого программного обеспечения) документов. Тем более – в ИТ.

Тут, конечно, справедливости ради, нужно сделать оговорку о том, что стандарт, регламентирующий рамку и основную надпись (ГОСТ 2.104), с 2024 года обновлён, в нём разделены теперь понятия«бумажный документ» и «электронный документ», и для электронного НАКОНЕЦ-ТАКИ (!) ввели разумные послабления (например, можно не делать ни рамку, ни основную надпись). Но до сих пор доводится встречать в контрактах требования следовать старым, уже не действующим, версиям ГОСТ.

Да, конечно, много вопросов к авторам (точнее, исполнителям)«римейков» старых стандартов. Но не меньше ��опросов и к тем, кто требует соблюдения очевидно устаревших нормативов, тем более для отрасли, для которой этот стандарт и не предназначался.

Вывод

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

Но в остальном – следует исповедовать принцип разумной достаточности. Жизнь не остановилась на лучине и лошади с повозкой. Надо жить сегодняшним днём, не загоняя себя в прокрустово ложе из рудиментов и атавизмов. Стандарты – это хорошо, но только когда они помогают, а не вредят процессу. Что стОит помнить при подготовке и заключении контрактов и организации проектов по автоматизации.