Создан 20.10.2012 18:15:57
Итак, сегодня наша главная тема - качество пользовательской документации. Но мы сочли для себя возможным слегка отойти от тематики, заявленной в плане секции, поскольку пользовательская - она же эксплуатационная программная документация, - всего лишь малая часть технической документации на продукцию вообще.
Почему целесообразно обсуждать вопросы качества техдокументации в целом? Потому, что помимо программ существует разнообразная электроника, бытовая техника (изделия), автоматизированные системы - все то, с чем нам так часто приходится сталкиваться в быту и на производстве. И на все это также разрабатывается пользовательская (эксплуатационная) документация. И не только пользовательская...
Коротко о качестве техдокументации
Коротко о качестве техдокументации. В своем докладе Миша Острогорский поведал нам о шедеврах пользовательской документации. Но в целом качество техдокументации, с которой нам приходилось когда-либо сталкиваться, мы считаем довольно низким.
Типичными примерами пришлось пожертвовать, поскольку на вычитку исходного варианта доклада ушло почти 50 минут. Но любой желающий может совершенно бесплатно предоставить нам на оценку любой самый лучший свой документ. Полный текст документа с указанием авторства, а также результаты его экспертизы будут опубликованы в течение нескольких дней на портале нашей компании.
Об экономической целесообразности повышения качества документации
Можно было бы сквозь пальцы смотреть на существующее положение дел в области качества документации, но не помешало бы задуматься о потерях:
- в бытовом плане - бренд теряет лицо, поскольку пользовательская документация - лицо компании. При низком ее качестве снижается конкурентоспособность продукции - покупатель десять раз подумает, приобретать ли у этой фирмы что-нибудь еще. И лишь злейшему врагу он посоветует покупать продукцию от этого производителя... Результат - прямые экономические потери;
- в производственном плане:
- обычно заказчик жестко контролирует подрядные организации и вправе не принимать работу у подрядчика, причем без какого-либо технического обоснования, а с чисто эмоциональной позиции: «Все то, что вы тут написали, - полный бред! Переделывайте». И приходится подрядчику переписывать документацию до бесконечности, причем за собственный счет, или до тех пор, пока заказчику самому не надоест играть в кошки-мышки;
- высокая вероятность поражения при конкурсных разработках. При проведении конкурсов очень часто проводится экспертиза технической документации, при этом документация низкого качества заведомо обречена на провал. Конкурс провален - деньги не получены. О том, как реально проводятся конкурсы, говорить не будем.
Очевидно, что качество техдокументации необходимо повышать, поскольку это экономически целесообразно, т.е. выгодно изготовителю продукции или подрядчику.
О разработке единой методики оценки качества технической документации
Исходя из экономической целесообразности, год назад мы начали разработку единой методики оценки качества техдокументации для получения быстрой, точной и объективной его оценки.
Почему объективной? А вспомните: «Все то, что вы тут написали, - полный бред! Переделывайте». Воспрепятствовать этому можно, но только доказав, что ваша документация полностью соответствует требованиям нормативных документов, включая требования к ее качеству.
Об инновационной составляющей разработки единой методики
Если набрать в любом поисковике словосочетание «качество (технической) документации», то можно легко убедиться в том, что данный вопрос, за исключением нашей компании, практически никогда и никем не затрагивался. Инновационная составляющая разработки методики очевидна.
О разработке методики оценки качества технической документации
Под методикой вообще принято понимать совокупность методов и приемов, опробованных и изученных для выполнения определенной работы. Остается решить, где взять эту совокупность. Наверное, самое разумное - ничего не выдумывать самим - все уже украдено до нас. Логика и здравый смысл подсказывают обратиться к нормативно-технической документации и определиться, какую НТД применить для разработки методики, т.е. составить минимальный ее перечень (номенклатуру).
Перечень НТД для разработки методики
В перечень нормативно-технической документации мы сочли целесообразным включить:
- ГОСТ 28195 Оценка качества программных средств. Общие положения;
- ГОСТ 2.105 ЕСКД. Общие требования к текстовым документам;
- ГОСТ 19.106 Единая система программной документации. Требования к программным документам, выполненным печатным способом;
- ГОСТ 8.417 Государственная система обеспечения единства измерений. Единицы физических величин.
Смотрите: |
Почему на основе НТД вообще и ГОСТов в частности?
Кто-то спросит: а почему разработку надо вести на основе НТД вообще и ГОСТов в частности? Потому, что НТД и, в частности, государственные стандарты, являются признанными и узаконенными государством наборами методов, приемов, способов выполнения определенных работ, а также оценки их качества. Именно поэтому мы выбрали ГОСТы.
Почему не IEEE?
Почему не IEEE? Специально для любопытных: в недалеком прошлом на нашем портале была опубликована статья «Как писать руководство пользователя? Часть I», содержащая сравнительный анализ ГОСТов 19-й системы и схожих стандартов IEEE. В статье показано, что современные стандарты IEEE и «рядом не стояли» с «безнадежно устаревшей» ЕСПД. ГОСТы 19-й системы вовсе не устарели, просто некоторые «не умеют их готовить»...
Почему в качестве базового выбран ГОСТ 28195?
Почему же в качестве базового выбран ГОСТ 28195 Оценка качества программных средств. Общие положения? С ГОСТ 2.105 ЕСКД Общие требования к текстовым документам все прозрачно, поскольку он и содержит общие требования к текстовым документам, как и ГОСТ 19.106 к программным, выполненным печатным способом. С ГОСТ 8.417 тоже все прозрачно - чистая метрология, а в данном случае - контроль корректности сокращения единиц физических величин...
Итак, смотрим определение. Программное средство; ПС (software) - объект, состоящий из программ, процедур, правил, а также, если предусмотрено, сопутствующих им документации и данных... [из 2 разд. 1 ГОСТ 28806-90].
Из определения следует, что программное средство, как и программное обеспечение, включают в свой состав помимо собственно программы еще и программную документацию. Т.е. помимо качества самой программы оценивается и качество программной документации. И, как показала практика, не только программной, но и любой технической. Именно поэтому в качестве базового был выбран ГОСТ 28195.
О методах оценки качества ТД по ГОСТ 28195
В ГОСТ 28195 предлагаются преимущественно экспертный и расчетный методы оценки качества. Согласно 1.5.5 ГОСТ 28195-89 определение значений показателей качества ПС экспертным методом осуществляется группой экспертов-специалистов, компетентных в решении данной задачи, на базе их опыта и интуиции.
Но интуиция - вещь субъективная... В сотый раз приходится возвращаться к типично-безграмотному требованию, тиражируемому практически в каждом ТЗ по ПО: «программа должна быть оснащена интуитивно-понятным пользовательским интерфейсом». Но тогда в требования к пользователю следует добавлять «пользователь должен обладать понятливостью и интуицией».
Итак, экспертный метод является весьма сомнительным, поэтому в своей методике мы предпочли применять расчетный там, где он только возможен. Ведь еще Михайло Васильевич Ломоносов говаривал: «Все похерить, что ни взвесить, ни измерить...»
Отбор оценочных элементов, подходящих для оценки качества техдокументации, из ГОСТ 28195
Всего в ГОСТ 28195 имеется шесть оценочных факторов, каждый из которых содержит свой перечень оценочных элементов:
- фактор надежности - 23 оценочных элемента;
- фактор сопровождаемости - 20;
- фактор удобства применения - 62;
- фактор эффективности - 19;
- фактор универсальности - 51;
- фактор корректности - 70 оценочных элементов.
При разработке методики мы выбрали по каждому из факторов определенный набор оценочных элементов, подходящих для оценки качества техдокументации, а также решили вопросы:
- целесообразности применения каждого из оценочных элементов (и возможность их исключения из состава метрик);
- целесообразности замены экспертных методов оценки расчетными;
- применимости оценочных элементов к конкретным видам документов вплоть до их разделов, подразделов, пунктов, подпунктов и т.д.
Общее количество оценочных элементов в ГОСТ 28195 - 245, поэтому рассмотрим лишь несколько из них, в основном по фактору удобства применения. В деталях все можно изучить в цикле статей «О качестве» на портале tdocs.su. Материалов по качеству техдокументации там уже хватит на целую книгу...
О некоторых оценочных элементах
Итак, о некоторых оценочных элементах...
Наличие краткой аннотации
Конкретный, но формальный оценочный элемент. Аннотация предусмотрена:
- в типовых проектных решениях по ГОСТ 24.703;
- в программных документах, см. Общие требования к программным документам по ГОСТ 19.105-78;
- в отчете о научно-исследовательской работе по ГОСТ 7.32-2001, только называется в нем рефератом;
- наверняка и еще где-то предусмотрена...
Аннотация может нравиться или не нравиться (с позиции эмоциональной), быть хорошей или плохой (с позиции оценки ее полноты, точности, достаточности, соответствия, краткости - обо всем этом ниже), но если она имеется - получаем единичку, нет - получаем ноль.
Наличие описания решаемых задач
Та же история, что и выше: наличие описания решаемых задач проверяется в описании программы, описании применения и в ряде иных программных документов, но описание может быть как хорошим, так и плохим, может нравиться или не нравиться.
Наличие описания основных функций ПС
Трудно себе представить, что в руководстве, инструкции или ином документе возможно отсутствие описания основных функций... Налицо логическое противоречие, поскольку любое изделие, включая программные изделия, для чего-нибудь да предназначено. А коль скоро есть назначение, то есть решаемые задачи и выполняемые функции, которые должны быть детально расписаны.
Другое дело, когда из-за лени или неопытности исполнителя некоторая часть основных функций не упоминается, но это уже вопрос полноты реализации ПС и достаточности описания основных функций.
Но не следует забывать и о том, что исполнитель может оказаться ВРАГОМ НАРОДА или НАЦИОНАЛ-ПРЕДАТЕЛЕМ, а враг, как известно, не дремлет, а еще он хитер и коварен. Поэтому не следует забывать о том, что существуют:
- Недекларированные возможности (программного обеспечения) по Р 50.1.056-2005;
- Недекларированные возможности по ГОСТ Р 53114-2008;
- Недекларированные возможности по РД ГТК Защита от НСД. ПО СЗИ. Классификация по уровню контроля отсутствия недекларированных возможностей;
- Программные закладки по РД ГТК Защита от НСД. ПО СЗИ. Классификация по уровню контроля отсутствия недекларированных возможностей;
- и еще много различных тайных подлостей.
Даже если речь не идет о защите информации от (иностранной) разведки по ГОСТ Р 50922-2006, то надо помнить о вирусописателях и вирусологах (есть мнение, что это одни и те же люди - и тоже враги народа). Все они обогащаются на публике, которая по недоумию или лени не перешла еще на операционные системы, разрабатываемые как свободное программное обеспечение.
Наличие описания алгоритмов
Пункт правильный, наличие проверяется в документах:
- описание алгоритма (проектной процедуры) по РД 50-34.698-90;
- описание программы по ГОСТ 19.402-78;
- и в ряде других документов.
Соответствие оглавления содержанию документации
Налицо очередная нестыковка с ГОСТ 2.105: оглавление в нем именуется содержанием, что не есть хорошо, поскольку под содержанием понимают еще и информационное наполнение документа - текст, графику, таблицы и проч. - все то, что размещается внутри разделов, подразделов, пунктов и подпунктов документа. С ГОСТ 19.106-78 нестыковка тоже есть, см. здесь. Содержание неплохо было бы заменить содержимым.
Как уже упоминалось в подразделе Навигация в электронных документах одной из предшествующих статей цикла, содержание гарантированно будет соответствовать структуре разделов и проч. документа в том случае, когда оно собирается из них автоматически. Многие, зная об этом, продолжают собирать содержание вручную 😉 Поэтому при малейшем несоответствии следует ставить нулевую оценку.
Грамматическая правильность изложения документации
Оценка - задача литературных редакторов и корректоров, но никак не всяческих «чекеров». Опять же нет ясности, как оценивать? Разработчики ГОСТ 28195 могли бы придумать формулу для оценки, например в виде отношения числа грамматических ошибок к общему числу слов (состоящих более чем из двух букв) в документе... И, если это отношение не выходило бы за определенные пределы, можно было бы смело ставить единичку.
Отсутствие неправильных ссылок
Под неправильными ссылками, судя по всему, следует понимать ссылки, ведущие не туда, куда надо, а то и вовсе в никуда... Предпочтителен расчетный метод.
Оценка по числу ссылок вперед в тексте документов
Ух... Ссылка вперед - это хорошо или плохо? В понимании автора - роскошно, если ссылка вперед содержит текст вида «детальные сведения о том-то приведены в подразделе таком-то». Строго соблюдается Краткость, отсутствие лишней детализации, а как улучшается навигация в документах, особенно бумажных! См. Пути улучшения навигации в бумажных документах.
Наличие предметного указателя
Комментировать нечего - либо наличие, либо отсутствие. Отсутствие, наверное, плохо, наличие - хорошо.
Логический порядок частей внутри главы
О каких частях и главах идет речь? И о каком порядке? Главы и части глав ни ГОСТ 2.105, ни ГОСТ 19.106-78 не предусмотрены, предусмотрены разделы, подразделы, пункты, подпункты и перечисления, а логический их порядок регламентируется стандартами, определяющими требования к структуре (составу) и содержанию конкретных документов.
Уровень языка общения пользователя с программой
Уровень языка общения пользователя с программой. Если тайный замысел разработчика ГОСТ 28195 понят автором правильно, то наивысшим уровнем языка взаимодействия пользователя с программой или техническими средствами является естественный для пользователя язык... Требование может быть сформулировано в подразделе Требования к лингвистическому обеспечению технического задания.
Результаты исследований
Краткие выводы по ГОСТ 28195
Выводы такие:
- ГОСТ 28195 тяжеловат для восприятия в силу его формализованности;
- при всей формализованности стандарта четко прослеживается его ахиллесова пята (слабое звено) - оценочные элементы, составляющие метрики.
Если дать волю эмоциям, то можно смело утверждать, что оценочные элементы описаны крайне небрежно. При сдержанной оценке вырисовывается следующее:
- оценочные элементы не раскрыты, что допускает множественное их толкование и, соответственно, сводит на нет практическое применение неплохого в целом стандарта;
- для оценок применяются (в подавляющем большинстве случаев) экспертные методы, хотя для того же подавляющего большинства оценочных элементов целесообразно применение расчетных методов.
Сложность поиска соответствующих разделов документов для сопоставления их с оценочными элементами факторов
И все бы терпимо, но возникает самый главный вопрос: а к какому разделу (подразделу, пункту, подпункту) можно применить каждый конкретный оценочный элемент? Что с чем сопоставлять?
Создание таблицы соответствия разделов документов оценочным элементам методики
Для решения этой проблемы мы подготовили таблицу соответствия, в которой для каждого конкретного оценочного элемента указали соответствующий раздел (подраздел и т.д.) конкретного документа. Если на первые оценки качества мы тратили втроем три рабочих дня, разыскивая в документах соответствующие оценочным элементам разделы, то сейчас вся работа проводится в течение нескольких часов.
Оценка технико-экономической эффективности внедрения
Оценить технико-экономическую эффективность внедрения можно, но сложно. Проще основываться на его экономической целесообразности, о которой было упомянуто выше.
Перспективы развития
Перспектива развития данной методики - привязка ее к автоматизированной системе технического документирования, разработанной нами еще в 2004 году. В итоге получится автоматизированная система разработки и оценки качества технической документации. Все это - дело ближайшего будущего.
Итоги
Итак, мы рассмотрели:
- экономическую целесообразность повышения качества техдокументации, см. Об экономической целесообразности повышения качества документации;
- необходимость и возможность разработки объективной методики оценки качества документации, см. О разработке единой методики оценки качества технической документации;
- обоснование применения общих положений ГОСТ 28195 не только для программ и программной документации, но и для документации вообще, см. Почему в качестве базового выбран ГОСТ 28195?;
- предпочтительность расчетных методов оценки экспертным, см. О методах оценки качества ТД по ГОСТ 28195;
- отдельные оценочные элементы, показав их достоинства и недостатки, в частности:
- показали связь оценочных факторов с конкретными документами, см. Наличие краткой аннотации;
- выявили абсурдность некоторых оценочных факторов, см. Наличие описания основных функций ПС;
- обнаружили отдельные нестыковки положений ГОСТ 28195 с ГОСТ 2.105 и ГОСТ 19.106, см. Соответствие оглавления содержанию документации;
- обосновали преимущества применения расчетных методов перед экспертными, см. Грамматическая правильность изложения документации.
Благодарю за внимание!
