Качество технической документации. Часть I

Первая статья цикла, посвященного оценке качества техдокументации. Цикл статей будет полезен:

• специалистам подрядных организаций, в чьи задачи входит разработка изделий, программных средств, автоматизированных систем и документации, сопровождающей стадии и этапы разработки, при приемосдаточных испытаниях, конкурсной разработке, если, конечно, важна победа, а не просто «техническое» участие в конкурсе;
• экспертам предприятий-заказчиков при приемке работ у подрядчиков;
• участникам конкурсных комиссий, готовящим экспертные заключения по документам, представленным участниками конкурса.

Качество технической документации. Часть I

Наиболее подходящими для решения задачи оценки качества технической документации являются, с нашей точки зрения, ГОСТ 2.105, ГОСТ 19.106-78 и ГОСТ 28195-89. Вызывает интерес и ГОСТ 8.417-2002 Государственная система обеспечения единства измерений. Единицы физических величин.

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

Качество технической документации - и это ни для кого не секрет - из года в год катастрофически снижается. Приведем пару примеров - «бытовой» и «инновационный».

«Семейная лодка разбилась о быт...»

Вот этикеточка на некое изделие, властью и непоколебимой волей технического писателя получившая гордое название «Руководство пользователя»...

«Языки пламени безжалостно лизали всю посуду, категорически оставляя на их пустом содержимом некрасивые пятна кондиционной влаги ...» Комментарии, как говорится, излишни, а «за пунктуацию таки и вовсе не имею шо сказать». Как будто бы и не существует п. 4.2.3 ГОСТ 2.105...

В тексте документа не допускается:

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

[из п. 4.2.3 ГОСТ 2.105]

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

Инновационный подход к проведению и документированию опытно-конструкторских работ (ОКР)

Цельнотянуто из Постановления Правительства РФ от 24 июля 1998 г. № 832 «О Концепции инновационной политики Российской Федерации на 1998 - 2000 годы». В словарь Ожегова, конечно же, авторы концепции не заглянули...

НОВОВВЕДЕНИЕ, -я, ср. Новое правило, вновь установленный порядок...
[Ожегов С. И. и Шведова Н. Ю. Толковый словарь русского языка: 80 000 слов и фразеологических выражений/ Российская академия наук. Институт русского языка им. В. В. Виноградова. - 4-е изд., дополненное. - М.: Азбуковник, 1999. - 944 стр.]

Определение инновации почему-то напомнило знаменитое «бой есть единственное средство достижения победы в бою» (из Полевого Устава РККА) или «я – командир первой эскадрильи, которой командую я!». Инновация раскрывается через инновационную деятельность, определение которой дано в следующем абзаце концепции. Но радует, что хоть не через самое себя...

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

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

В рамках указанных ОКР проводятся разработки комплексов программ, что, в идеале, подразумевает проведение работ согласно стадиям разработки по ГОСТ 19.102-77 Единая система программной документации. Министерские же мастера-умельцы потребовали разработку технических заданий по ГОСТ 15-й системы (что логично для ОКР), в технические задания заставили втиснуть структуру разделов ГОСТ 19.201-78 (что тоже логично), но этапы ОКР призвали выполнять по Единой системе конструкторской(!!!) документации - ГОСТ 2.119 для эскизного и ГОСТ 2.120 для технического проекта! Кстати, эскизные проекты отродясь никто не делал - наверное, это их маленький (министерский) каприз... Да и технический проект принято объединять с рабочей документацией в одну стадию - технорабочий проект.

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

И на десерт несколько перлов из технических заданий и календарных планов:

• «...обоснование характеристик сторонних программных средств...» - ласкает слух! Берем какую-нибудь стороннюю софтинку типа ворда и обосновываем ее характеристики ;
• «...унификация функциональных задач...» - см., уважаемые, определения функций и задач, хотя бы применительно к автоматизированным системам;
• «...графических элементов интерфейсов...» - вероятно, имеются в виду элементы графического интерфейса пользователя;
• «...графического интерфейса модулей...» - это уже придирка, конечно, но далеко не все программные модули оснащены графическим интерфейсом;
• «...сторонних систем...» - очевидно, речь идет о внешних системах;
• «...Технический акт...» - тут впору задумчиво почесать в затылке... Наверное, это что-то вроде загадочного зоологического термина «свинская собака» по Ярославу Гашеку;
• «...Документ «Обоснование необходимости закупки технических средств, программного обеспечения и лицензий на него»...» - косноязычие и полное непонимание сути проблемы... Обосновывать следует закупку технических средств с конкретными характеристиками, обеспечивающими конкретный вычислительный ресурс, требуемый для нормального (штатного) функционирования комплекса программ. Программное же обеспечение, если не приобретать пиратское, всегда продается совместно с лицензией. Но дорого, однако ;
• «...контролем входной и выходной информации, основанной на методике кодирования объектов...» - входная информация (или данные), вводимая пользователем вручную в диалоговом (или интерактивном) режиме с помощью элементов графического интерфейса в поля ввода данных, подвергается форматно-логическому контролю, проверке неких граничных условий. Чтобы сильно не грузить читателя, приведем простой пример: форматно-логический контроль не позволит ввести, допустим, дату смерти более раннюю, чем дату рождения индивида;
• «...Критерием предельного состояния Комплекса XYZ является превышение времени выполнения функций...» - уважаемые господа, посмотрите, пожалуйста, в ГОСТ 27.002, что есть предельное состояние...;
• «...с возможностью «горячего резервирования» и перехода на резервное оборудование...» - налицо нарушение п. 4.2.3 ГОСТ 2.105 и явное невладение терминологией. Горячего резервирования не существует в природе, есть постоянное резервирование, которое, как известно (немногим), не требует никаких переходов (переключений). Слово «оборудование» в рамках стандартов по информационным технологиям и системам обработки информации не применяется, есть понятие «технические средства», «техническое обеспечение» и т.д.;
• и, наконец, самое забавное - «...должна соответствовать требованиям эргономики и профессиональной медицины...»... Есть подозрение, что под профессиональной медициной подразумеваются СанПиНы - санитарные правила и нормы

Ради справедливости следует отметить, что все исполнители добросовестно и детально расписывают функционал комплексов программ, а также включают в свои ТЗ отдельные разделы статьи «Как писать техническое задание на программу по ГОСТ 19.201-78?», опубликованной автором лет семь-восемь тому назад еще на сайте authorit.ru, на котором сейчас обитает только форум проектировщиков и разработчиков технической документации.

Примечание - Гиперссылки в статье зачастую применимы исключительно к автоматизированным системам, но сути дела это не меняет.

Итак, о плачевном качестве нынешней документации, наверное, говорить больше не стоит. Без того грустно. Теперь немного об экспертизе технической документации при проведении конкурсов.

Экспертиза технической документации при проведении конкурсных разработок

Нынешним летом АНО «Спортивное вещание» проводило не совсем характерный для себя открытый конкурс, и в этой связи (для поддержки штанов) были привлечены специалисты «Технической документации». Сработала многолетняя дружба вкупе с опытом документирования портальных решений с миллионными ежесуточными посещениями и прямыми телевизионными трансляциями в сети Интернет (Интернет-портал телеканала «Спорт»). Задача сначала казалась тривиальной: всего-то надо было разработать конкурсное техническое задание, на основании которого участники конкурса должны были разработать свои развернутые варианты ТЗ, а затем определиться с компанией-победителем конкурса.

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

В данном конкретном случае технический уровень определялся прозрачностью и полнотой развернутого функционала, владением терминологией и оформлением документации, т.е. проводилась техническая экспертиза (по существу функционала), а затем что-то схожее с нормоконтролем и метрологической экспертизой. Как было указано выше, все экспертные процедуры проводились согласно ГОСТ 2.105, ГОСТ 19.106-78, ГОСТ 28195-89 и ГОСТ 8.417-2002.

Почему ГОСТ 28195-89?

Почему же выбран ГОСТ 28195-89 Оценка качества программных средств. Общие положения? С ГОСТ 2.105 ЕСКД Общие требования к текстовым документам все прозрачно, поскольку он и содержит общие требования к текстовым документам, как и ГОСТ 19.106-78 к программным, выполненным печатным способом. С ГОСТ 8.417-2002 тоже все прозрачно - чистая метрология, а в данном случае - контроль корректности сокращения единиц физических величин...

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

Теперь детально о ГОСТ 28195-89 с использованием аутентичного текста самого стандарта.

Согласно п. 1.1 ГОСТ 28195-89 оценка качества осуществляется на всех этапах жизненного цикла ПС при:

• планировании показателей качества ПС;
• контроле качества на отдельных этапах разработки (техническое задание, технический проект, рабочий проект);
• контроле качества в процессе производства ПС;
• проверке эффективности модификации ПС на этапе сопровождения.

Вообще-то согласно ГОСТ 19-й и 34-й систем техническое задание, технический проект и рабочий проект трактуются как стадии, см. Стадии разработки по ГОСТ 19.102-77 или Наименования документов, разрабатываемых при проектировании системы по ГОСТ 34.201-89. Неувязочка вышла... Также в тексте стандарта упоминаются невесть откуда взявшиеся фазы и этапы, а не стадии жизненного цикла... По несоответствиям в ГОСТ 28195-89 здесь и далее мы пройдемся весьма основательно.

Согласно п. 1.2 ГОСТ 28195-89 оценка качества ПС представляет собой совокупность операций, включающих выбор номенклатуры показателей качества оцениваемого ПС, определение значений этих показателей и сравнение их с базовыми значениями.

Согласно п. 1.5 ГОСТ 28195-89 методы определения показателей качества ПС различаются:

• по способам получения информации о ПС - измерительный, регистрационный, органолептический, расчетный;
• по источникам получения информации - традиционный, экспертный, социологический.

Согласно п. 1.5.5 ГОСТ 28195-89 определение значений показателей качества ПС экспертным методом осуществляется группой экспертов-специалистов, компетентных в решении данной задачи, на базе их опыта и интуиции.

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

В ГОСТ 28195-89 применяются, преимущественно, экспертные оценки. Но, как будет показано в последующих статьях, по ряду оценочных факторов целесообразно применять не экспертный, а расчетный метод оценки. Теперь немного о методике оценки качества, предусмотренной в данном стандарте.

Для обеспечения возможности получения интегральной оценки по группам показателей качества используют факторы качества (1-й уровень): надежность ПС, сопровождаемость, удобство применения, эффективность, универсальность (гибкость) и корректность [из п. 2.1 Прил. 2 ГОСТ 28195-89]

Если пройти по ссылкам, то можно убедиться в том, что в ГОСТ 28806-90 и ГОСТ 28195-89 с терминологическим единством дело обстоит неважно... Вероятно, это обусловлено годичной разницей в возрасте, но как-то странно все: сначала проводится оценка качества, а только год спустя формулируются комплексные показатели качества...

Каждому фактору качества соответствует определенный набор критериев качества (комплексные показатели - 2-й уровень): устойчивость функционирования, работоспособность, структурность, простота конструкции, наглядность, повторяемость, легкость освоения, доступность эксплуатационных программных документов, удобство эксплуатации и обслуживания, уровень автоматизации, временная эффективность, ресурсоемкость, гибкость, мобильность, модифицируемость, полнота реализации, согласованность, логическая корректность, проверенность [из п. 2.2 Прил. 2 ГОСТ 28195-89]

Критерии качества определяют одной или несколькими метриками (3-й уровень). Если критерий качества определяется одной метрикой, то уровень метрики опускается [из п. 2.3 Прил. 2 ГОСТ 28195-89]

Метрики составляются из оценочных элементов (единичных показателей - 4-й уровень), определяющих заданное в метрике свойство. Число оценочных элементов, входящих в метрику не ограничено. Взаимосвязь факторов, критериев и метрик с фазами жизненного цикла ПС приведена на черт. 1 - 20 [из п. 2.4 Прил. 2 ГОСТ 28195-89]

Первые выводы

Настоящая статья корректировалась 30.01.2012, к этой дате уже были опубликованы вторая и третья части статьи, на подходе выход в свет и четвертой. На основании перечисленного материал ГОСТ 28195-89 можно считать проработанным достаточно глубоко для того, чтобы сделать первые выводы. А выводы такие:

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

Если дать волю эмоциям, то можно смело утверждать, что оценочные элементы описаны крайне небрежно. При сдержанной оценке вырисовывается следующее:

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

В связи с соображениями, изложенными выше, в цикле статей будет сделан акцент именно на оценочные элементы, включая:

• их истолкование;
• пояснения (с примерами);
• целесообразность их применения (возможность исключения из состава метрик);
• целесообразность замены методов оценки;
• применимость оценочных элементов к конкретным видам документов.

Отдельно будет отмечена некоторая несогласованность ГОСТ 28195-89 со стандартами ЕСПД и ЕСКД - обратите внимание на слово черт в п. 2.4 Прил. 2 стандарта -

Заказать услуги, установить контакты со специалистами компании можно по электронной почте admin собака tdocs точка su, по ICQ UIN 481-726-610 или с помощью формы «Контакты». Вопросы некоммерческого характера могут быть заданы в Форуме проектировщиков и разработчиков технической документации.