Исследования и решения в области качества технической документации

О качестве технической документации. Исследования и решения

Вместо введения

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

Из доклада:

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

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

Коротко о качестве техдокументации на примерах

В своем докладе Миша Острогорский поведал нам о шедеврах пользовательской документации. Хочется несколько дополнить его выступление примерами из реальной жизни - как бытовыми, так производственными.

«Шедевры» пользовательской документации на товары народного потребления

Для справки: товары народного потребления - это Продукция, предназначенная для продажи населению с целью непосредственного использования ее для удовлетворения материальных и культурных потребностей. Товары народного потребления подразделяются на продовольственные и непродовольственные. К последним относятся товары культурно-бытового, хозяйственного назначения, продукция легкой промышленности и т.д. Особенности создания товаров народного потребления установлены почти во всех общих стандартах СРПП. Некоторые виды продукции могут одновременно использоваться как продукция производственно-технического назначения и как товары народного потребления [из п. 1.2.3 Р 50-605-80-93]

Руководство пользователя сковороды

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

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

Под синеватым окрасом, скорее всего, имеются в виду т.н. «цвета побежалости», но вот сколько и посудине какого объема надо развести лимонной кислоты, чтобы опустить в этот раствор сковороду диаметром 280 мм и высотой 70 мм? И это без учета рукоятки длиной 220 мм

Каков вывод? Руководство косноязычно и абсолютно неинформативно. И грош ему цена.

Руководство пользователя мобильного телефона

У меня в руках обыкновенный мобильный телефон с двумя sim-картами. Известного производителя. Руководство на него так не раскрыло тайны переключения sim-карт «на лету», без перезагрузки телефона... Выручил, в итоге, «метод Монте-Карло», он же «метод научного тыка».

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

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

Инструкция по эксплуатации комбинированной маятниковой и настольной циркулярной пилы

Инструкция по эксплуатации комбинированной маятниковой и настольной циркулярной пилы - тоже передовой край эргономики, в простонародье называемой юзабилити...

Обратите внимание на то, что собственно работа с пилой расписана на страницах с 13-й по 16-ю, а поясняющие рисунки, на которые следуют ссылки с указанных страниц - со 2-й по 4-ю. Пользователю вряд ли удобно ежеминутно перелистывать с десяток страниц туда-обратно. Более того, рисунки в оригинале руководства представлены в черно-белом варианте с оттенками серого, поэтому разобрать на них, что какой позиции соответствует, почти невозможно. На рисунке ниже изображено чудо немецкой техники в своем естественном виде...

Холодильник

При доставке нового холодильника мне сразу же объяснили, что включать его в сеть можно не ранее 2-х часов после установки - хладоагент в нем должен устаканиться - иначе холодильник может выйти из строя. В инструкции, разумеется, об этом не было сказано ни слова... Вывод: инструкция - самый настоящий злой умысел.

И самый курьезный случай: однажды попал мне в руки документ на какое-то оборудование автоматизации котельной. В нем было написано буквально так: «Если у вас не получилось сделать (что-то), вы не переживайте...» Здесь хоть прослеживается забота о пользователе

«Шедевры» документации на продукцию производственно-технического назначения

Теперь о «шедеврах» на продукцию производственно-технического назначения. Кстати, один знакомый, очень опытный метролог, как-то раз написал на 50-страничную методику проведения предпроектного обследования более трехсот замечаний. У меня опыта поменьше...

Итак, продукция производственно-технического назначения - Продукция для использования в качестве средств промышленного и сельскохозяйственного производства [из п. 1.2.2 Р 50-605-80-93]

Приведу фрагменты из типового ТЗ, разработанного самым грамотным отечественным министерством. Как все уже догадались, речь идет о Министерстве образования и науки:

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

Об экономической целесообразности разработки качественной технической документации

О «шедеврах», пожалуй, достаточно. Можно было бы сквозь пальцы смотреть на существующее положение дел в области качества документации, но не помешало бы и оценить потери:

• в бытовом плане - брэнд теряет лицо, поскольку пользовательская документация - лицо компании (туалет - лицо хозяйки! «Harpic», средство для сантехники и кафеля). При низком качестве техдокументации снижается конкурентноспособность продукции - покупатель решает больше продукцию этой фирмы не приобретать. И тут же срабатывает сарафанное радио: вот купил, сдуру, то-то, и не пойму, как пользоваться. В руководстве пользователя сам черт ногу сломит... Не вздумай никогда и ничего покупать от этого производителя... Налицо негативная окраска брэнда «в народе», оборачивающаяся экономическими потерями и убытками;
• в производственном плане:
  1. при жестком контроле со стороны заказчика подрядных организаций заказчик вправе не принять работу у подрядчика, причем без какого-либо технического обоснования. С чисто эмоциональной позиции: «Все то, что вы тут понаписали - полный бред! Переделывайте». И придется подрядчику переделывать документацию до бесконечности, причем за собственный счет, или до тех пор, пока заказчик сам не устанет играть в кошки-мышки;
  2. высокая вероятность потерпеть поражение при конкурсных разработках. При проведении конкурсов очень часто проводится экспертиза технической документации, документация низкого качества заведомо обречена на провал. Конкурс провален - деньги не получены. О том, как реально проводятся конкурсы, говорить не будем.

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

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

Именно из экономической целесообразности вытекает необходимость разработки единой методики оценки качества технической документации (далее - методики), позволившей бы быстро и точно дать качеству документации достаточно объективную оценку.

Почему объективную? А вспомните: «Все то, что вы тут понаписали - полный бред! Переделывайте». Воспрепятствовать этому можно, но только доказав, что ваша документация полностью соответствует требованиям нормативно-технических документов, включая требования к ее качеству.

Об инновационной составляющей такого решения

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

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

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

Перечень НТД для разработки методики

В перечень нормативно-технической документации целесообразно ввести:

• ГОСТ 28195 Оценка качества программных средств. Общие положения;
• ГОСТ 2.105 ЕСКД. Общие требования к текстовым документам;
• ГОСТ 19.106 Единая система программной документации. Требования к программным документам, выполненным печатным способом;
• ГОСТ 8.417 Государственная система обеспечения единства измерений. Единицы физических величин.

Почему на основе НТД вообще и ГОСТ в частности?

Кто-то спросит: а почему разработку надо вести на основе НТД вообще и ГОСТ в частности? Потому, что НТД и, в частности, государственные стандарты, являются признанными и узаконенными государством наборами методов, приемов, способов выполнения определенных работ.

Стандарт есть НОРМА, свод норм и правил, свойств... (подобное определение вы найдете в любом толковом словаре).

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

А это из «всеми любимого» ФЗ о «Техническом регулировании».

Таким образом, разработку методики разумнее всего проводить на основе ГОСТ.

Почему не IEEE?

Почему не IEEE? Специально для любопытных: в недалеком прошлом была подготовлена и опубликована статья «Как писать руководство пользователя? Часть I», содержащая сравнительный анализ ГОСТ 19-й системы и отдельных стандартов IEEE. В статье убедительно доказано, что современные стандарты IEEE и «рядом не стояли» с «безнадежно устаревшей» ЕСПД. ГОСТ 19-й системы вовсе не устарели, просто некоторые «не умеют правильно их готовить»...

Почему в качестве базового выбран ГОСТ 28195?

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

Смотрим определения.

Объект, состоящий из программ, процедур, правил, а также, если предусмотрено, сопутствующих им документации и данных, относящихся к функционированию системы обработки информации. Примечание - Программное средство представляет собой конкретную информацию, объективно существующую как совокупность всех значимых с точки зрения ее представлений свойств каждого из материальных объектов, содержащих в фиксированном виде эту информацию [из п. 2 разд. 1 ГОСТ 28806-90]

1. Под процедурами и правилами подразумевается порядок действий, применяемый для решения задачи.
2. Объем понятия, выражаемого производным термином «программные средства», включает в себя как частный случай объем понятия «программное обеспечение» определяемого по ГОСТ 19781.
3. Эквивалентом производного термина «программные средства» на английском языке является термин software, используемый в своем собирательном значении (например mathematical software - программные средства для математических задач).
4. Грамматика английского языка позволяет однозначно указывать с помощью артикля конкретное значение термина software, который при такой форме его использования является основным эквивалентом термина «программное средство» (например «the Turbo Pascal 5.0 software» — «программное средство Турбо Паскаль 5.0»). В отдельных случаях (например, когда по смыслу требуется неопределенный артикль) правила и нормы языка делают необходимым использование другого эквивалента - software entity.
5. При образовании терминов-словосочетаний значение «имеющий отношение к программным средствам» выражается на русском языке терминоэлементом «программный», на английском языке - словом software в роли прилагательного (например «программный продукт», software product).

[из прил. 1 ГОСТ 28806-90]

Совокупность свойств программного средства, которые обусловливают его пригодность удовлетворять заданные или подразумеваемые потребности в соответствии с его назначением [из п. 6 разд. 1 ГОСТ 28806-90]

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

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

Исследования и отбор методов оценки качества ТД по ГОСТ 28195

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

Но интуиция - вещь субъективная... В который раз приходится возвращаться к типично-безграмотному требованию, тиражируемому практически в каждом ТЗ по ПО: «программа должна быть оснащена интуитивно-понятным пользовательским интерфейсом». Но тогда в требования к пользователю следует добавлять «пользователь должен обладать понятливостью и интуицией». Отличные требования, правда?

Итак, поскольку экспертный метод явно является сомнительным, предпочтителен расчетный, поскольку еще Михаил Васильевич Ломоносов говаривал: «Все похерить, что ни взвесить, ни измерить...»

Исследование и отбор оценочных элементов, подходящих для оценки качества техдокументации, из ГОСТ 28195

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

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

К сожалению, времени на доклад выделено очень немного, а общее количество оценочных элементов - 245, потому далее - «галопом по европам». Только самое интересное. В деталях все можно изучить в цикле статей «О качестве» на портале tdocs.su. Материалов по качеству техдокументации там уже хватит на целую книгу...

Перечень оценочных элементов фактора надежности

Рассмотрим несколько оценочных элементов фактора надежности, применимых к технической документации (общее количество оценочных элементов фактора надежности - 23).

Примечание - Здесь и далее требования в оценочных элементах будут применяться все больше к техническому заданию на автоматизированную систему, поскольку:

• ТЗ на АС наиболее востребованы на текущий момент, да и оценки часто касаются именно требований;
• на примере ТЗ можно с максимумом наглядности показать способы достижения того самого предопределенного качества документа, о котором упоминалось выше.

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

Наличие требований к программе по устойчивости функционирования при наличии ошибок во входных данных

«Наличие... при наличии...»

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

Полнота обработки ошибочных ситуаций

Полнота обработки ошибочных ситуаций - в документах должен быть приведен полный перечень ошибочных ситуаций. Если предусмотрена обработка всех ошибочных ситуаций, то полноту обработки можно считать 100-процентной.

Наличие тестов для проверки допустимых значений входных данных

Критерий звучит несколько старообразно. Сейчас, когда практически все программы оснащены графическим интерфейсом пользователя, допустимые значения входных данных, вводимых пользователем в диалоговом или интерактивном режиме, проходят форматно-логический контроль.

Контроль формата ввода данных: программа позволяет пользователю вводить дату только в формате ДД.ММ.ГГГГ, но не в ГГГГ/ММ/ДД и ни в каком ином. Логический контроль: дата окончания школы не может быть введена БОЛЕЕ ранней, нежели чем дата поступления в школу

О форматно-логическом контроле следует упомянуть где-нибудь в подразделе Требования к лингвистическому обеспечению или создать дополнительный подраздел «Требования к интерфейсу пользователя» в техническом задании.

Наличие средств контроля корректности входных данных

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

Наличие требований к программе по восстановлению процесса выполнения в случае сбоя операционной системы, процессора, внешних устройств

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

Наличие возможности разделения по времени выполнения отдельных функций программ

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

Наличие централизованного управления процессами, конкурирующими из-за ресурсов

Централизованное управление процессами, конкурирующими из-за ресурсов, встроено во все применяемые ныне операционные системы. Требования к операционным системам, входящим в состав общего программного обеспечения, расписываются в подразделе Требования к программному обеспечению технического задания.

Наличие средств, обеспечивающих завершение процесса решения в случае помех

Не совсем ясно, что считать помехами? Если это какие-нибудь электромагнитные помехи или внешние воздействующие факторы по ГОСТ 26883-86, то следует озвучить заданное требование в техническом задании, а в подразделе Требования к защите от влияния внешних воздействий указать предельные их уровни, например «...соответствие нормам индустриальных помех для оборудования класса А согласно ГОСТ Р 51318.22 (СИСПР 22-97)».

Перечень оценочных элементов фактора сопровождаемости

Рассмотрим несколько оценочных элементов фактора сопровождаемости, применимых к технической документации (общее количество оценочных элементов фактора сопровождаемости - 20).

Наличие модульной схемы программы

Модульная схема может быть предусмотрена в требованиях технического задания, а проверить ее наличие можно в документе описание программы или ему подобном.

Оценка простоты программы по числу точек входа и выхода

Не совсем понятный критерий: сколько точек входа (выхода) необходимо, чтобы считать программу простой?

Соответствие комментариев принятым соглашениям

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

Оценка ясности и точности описания последовательности функционирования всех элементов программы

С точностью более-менее понятно, поскольку ее можно оценить простой сверкой работы программы с описанием применения. А что понимать под ясностью? Ясность формулировок и описаний?

В обоих случаях экспертный метод оценки применим мало.

Использование типовых компонентов ПС

Использование типовых компонентов ПС - это что-то вроде применения типовых проектных решений.

Перечень оценочных элементов фактора удобства применения

Рассмотрим несколько оценочных элементов фактора удобства применения, применимых к технической документации (общее количество оценочных элементов фактора удобства применения - 62).

Возможность поэтапного освоения ПС

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

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

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

Наличие краткой аннотации

Конкретный, но формальный оценочный элемент. Аннотация предусмотрена:

• в типовых проектных решениях по ГОСТ 24.703;
• в программных документах, см. Общие требования к программным документам по ГОСТ 19.105-78;
• в отчете о научно-исследовательской работе по ГОСТ 7.32-2001, только называется в нем рефератом;
• наверняка и еще где-то предусмотрена...

Аннотация может нравиться или не нравиться (с позиции эмоциональной), быть хорошей или плохой (с позиции оценки ее полноты, точности, достаточности, соответствия, краткости - обо всем этом ниже), но если она имеется - получаем единичку, нет - получаем ноль.

Наличие описания основных функций ПС

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

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

Но не следует забывать и о том, что исполнитель может оказаться ВРАГОМ НАРОДА или НАЦИОНАЛ-ПРЕДАТЕЛЕМ, а враг, как известно, не дремлет, а еще он хитер и коварен. Поэтому не следует забывать о том, что существуют:

1. Недекларированные возможности (программного обеспечения) по Р 50.1.056-2005;
2. Недекларированные возможности по ГОСТ Р 53114-2008;
3. Недекларированные возможности по РД ГТК Защита от НСД. ПО СЗИ. Классификация по уровню контроля отсутствия недекларированных возможностей;
4. Программные закладки по РД ГТК Защита от НСД. ПО СЗИ. Классификация по уровню контроля отсутствия недекларированных возможностей;
5. и еще много различных тайных подлостей.

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

Наличие описания алгоритмов

Пункт правильный, наличие проверяется в документах:

• описание алгоритма (проектной процедуры) по РД 50-34.698-90;
• описание программы по ГОСТ 19.402-78;
• и в ряде других документов.

Наличие описания межмодульных интерфейсов

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

Наличие описания пользовательских интерфейсов

Наука выделяет два основных вида пользовательских интерфейсов:

• графический интерфейс пользователя;
• интерфейс командной строки.

Графический интерфейс пользователя представлен на рисунке ниже.

В данном варианте интерфейса, представленном в виде мегаменю, описывать нечего, поскольку меню развернуто на все три уровня вложенности, все видно и так. Если речь идет об интерфейсе какой-либо прикладной программы, то придется изрядно потрудиться. Чтобы не перегружать без того большущую статью, сошлемся на книжку «Автоматизация разработки технической документации с применением AuthorIT. Учебное пособие», в которой пользовательский интерфейс программы AuthorIT расписан очень подробно.

Ниже показан интерфейс командной строки с описанием синтаксиса команд и их параметров. Комментарии, наверное, излишни.

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

• microsoft.com/Language/ru-ru/Terminology.aspx;
• microsoft.com/Language/ru-ru/StyleGuides.aspx.

Наличие описания входных и выходных данных

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

Примеры с поисковой системой Яндекс показаны на рисунках. Входными данными является информационный запрос, выходными - результат поиска.

С выходными данными ситуация аналогичная. Описания входных и выходных данных (программы) должны быть в документах:

• описание программы;
• описание применения;
• и в ряде других документов.

Наличие описания диагностических сообщений

Наличие описания диагностических сообщений... Диагностические сообщения программы формируются в ходе технического диагностирования встроенными средствами технической диагностики согласно алгоритму диагностирования в рамках диагностической модели. Диагностические сообщения должны быть описаны в:

• руководстве оператора;
• руководстве программиста;
• руководстве системного программиста.

Достаточность документации для ввода ПС в эксплуатацию

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

Соответствие оглавления содержанию документации

Налицо очередная нестыковка с ГОСТ 2.105: оглавление в нем именуется содержанием, что не есть хорошо, поскольку под содержанием понимают еще и информационное наполнение документа - текст, графику, таблицы и проч. - все то, что размещается внутри разделов, подразделов, пунктов и подпунктов документа. С ГОСТ 19.106-78 нестыковка тоже есть, см. здесь. Содержание неплохо было бы заменить содержимым.

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

Оценка оформления документации

Оформление может нравиться или не нравиться - дело вкуса, если воспринимать оценочный элемент не слишком буквально. Если подойти вдумчиво, то элемент является обобщающим и итоговым. Т.е. если оформление документации по всем прочим оценочным элементам оформления зарабатывает единицы, то и итоговый потянет на единичку. Но лучше было бы просуммировать баллы...

Грамматическая правильность изложения документации

Оценка - задача литературных редакторов и корректоров, но никак не всяческих «чекеров». Опять же нет ясности, как оценивать? Разработчики ГОСТ 28195 могли бы придумать формулу для оценки, например в виде отношения числа грамматических ошибок к общему числу слов (состоящих более чем из двух букв) в документе... И, если это отношение не выходило бы за определенные пределы, можно было бы смело ставить единичку.

Отсутствие противоречий

Противоречие - несогласованность, антоним согласованности. См. также Отсутствие ненужных повторений. Было бы неплохо применить расчетный метод оценки, поскольку одно или несколько противоречий погоды не делают, но когда их десятки и сотни...

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

Отсутствие неправильных ссылок

Под неправильными ссылками, судя по всему, следует понимать ссылки, ведущие не туда, куда надо, а то и вовсе в никуда... Предпочтителен расчетный метод.

Ясность формулировок и описаний

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

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

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

Словарь по логике. - М.: Туманит, изд. центр ВЛАДОС. А.А.Ивин, А.Л.Никифоров. 1997»

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

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

Изложение текстов «вообще»

Создан 28.12.2006 17:57:32

Любой текст, как технический, так и нетехнический, воспринимается разными людьми по-разному¹ - многое зависит их от возраста, уровня подготовленности и ряда других объективных факторов. Особенность технического текста, например текста руководства пользователя, состоит в том, что любая из категорий пользователей, следуя инструкциям руководства, должна получить один и тот же результат². В указанном случае текст руководства пользователя можно справедливо считать грамотно изложенным.

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

Примечания от 17.05.2018:

1. Аудитория (Audience) по ГОСТ Р ИСО/МЭК 15910-2002.
2. Единственное же НАШЕ требование к пользователю - умение читать и оперировать графическим пользовательским интерфейсом, тогда результат гарантирован. Если же руководство предполагает, что пользователь должен уметь думать, соображать и при этом еще чего-то требовать, чтобы достичь ожидаемого результата - грош цена такому руководству, а в особенности - его автору. Но прежде всего - грош цена ГОСТ Р ИСО/МЭК 15910-2002.

Создан 28.12.2006 18:55:08

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

1 Переменные AuthorIT

1.1 Назначение переменных AuthorIT

Переменные AuthorIT предназначены:

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

1.2 Состав переменных AuthorIT

В состав переменных AuthorIT входят переменные перечисленных ниже видов:

• Text;
• List Of Values;
• File Objects;
• System.

1.2.1 Назначение переменных Text

Переменные Text предназначены:

• для хранения фрагментов текста в виде значений переменных;
• для замещения фрагментов текста короткими именами переменных в топиках AuthorIT;
• для замещения имен переменных фрагментами текста в публикуемых документах;
• для публикации различных фрагментов текста в различных версиях типовых документов.

1.2.2 Состав переменных Text

В состав переменной Text входит строка текста, включающая в себя от 0 до 2000 символов.

И так далее. При изложении текста по схеме назначение⇨состав структурированный текст получается у пишущего самопроизвольно, без каких-либо усилий - в разделе 1 образовались подразделы 1.1 и 1.2, в подразделе 1.2 образовались пункты 1.2.1 и 1.2.2 - текст приобрел иерархическую структуру. При изложении текста руководства удобно применять схему действие⇨результат, реализованную во всех разделах книги, за исключением разделов Введение и Заключение - «нажать кнопку... - AuthorIT откроет окно...»

Создан 28.12.2006 18:55:51

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

Пользователь на основе шаблона sample.adl создает библиотеку. Библиотека может содержать папки. Папки служат контейнерами для одной или нескольких книг. Книга может включать в себя титульный лист, содержание, топики и иные структурные элементы. Структурные элементы книги образуют древовидную иерархическую структуру книги...

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

Правильность использования терминов

Использование тоже какое-то нехорошее слово, см. Ясность формулировок и описаний. «Я тебя любила, а ты меня использовал!» Есть же синоним применение, наиболее применимый применительно к стилю изложения...

Термины желательно не просто применять, но еще и раскрывать. Ведь от обычной ссылки на ГОСТы (что-то такое по ГОСТ такому-то) положительных эмоций ожидать не приходится. Скорее наоборот: читающему придется перелопатить кучу стандартов, разыскать термин, прочесть его определение... Зачем издеваться над людьми?

Пример правильного применения терминов приведен здесь.

Краткость, отсутствие лишней детализации

Краткость, как известно, сестра таланта, но враг гонорара... Лишней детализации не бывает, детализация должна проводиться вплоть до атомарного уровня, см. здесь.

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

Единство обозначений

Единство обозначений: речь, судя по всему, идет об исключении применения синонимов для одного и того же понятия, как требует п. 4.2.3 ГОСТ 2.105.

Ясность логической структуры

Логическая структура определяется требованиями ГОСТов к структурам и содержанию соответствующих документов и может считаться ясной по умолчанию. Т.е. проверять надо структуру и содержание на соответствие требованиям ГОСТов.

Соблюдение стандартов и правил изложения в документации

Данный оценочный элемент, как Возможность освоения программных средств по документации, Достаточность документации для ввода ПС в эксплуатацию и Оценка оформления документации, следует считать обобщающим.

Оценка по числу ссылок вперед в тексте документов

Ух... Ссылка вперед - это хорошо или плохо? В понимании автора - роскошно, если ссылка вперед содержит текст вида «детальные сведения о том-то приведены в подразделе таком-то». Строго соблюдается Краткость, отсутствие лишней детализации, а как улучшается навигация в документах, особенно бумажных! См. Пути улучшения навигации в бумажных документах.

Наличие оглавления

Очередной повтор, см. Соответствие оглавления содержанию документации.

Наличие предметного указателя

Комментировать нечего - либо наличие, либо отсутствие. Отсутствие, наверное, плохо, наличие - хорошо.

Наличие перекрестных ссылок

По аналогии с п. Оценка по числу ссылок вперед в тексте документов, только оценка пусть остается экспертной.

Наличие всех требуемых разделов

Наличие всех требуемых разделов определяется разработчиком, см. здесь, здесь, руководство оператора, руководство программиста, руководство системного программиста... Достаточно, наверное.

Нюанс состоит в том, что разработчик себе не хозяин в полном смысле слова, см. здесь... Состав требуемых разделов разумнее согласовать с заказчиком. Тогда проверять их наличие и «требуемость» будет легко и просто.

Соблюдение непрерывности нумерации страниц документов

Обеспечивается элементарно любыми текстовыми процессорами. Но пролистать документ не помешает, поскольку порой бывают и сбои нумерации. Автор пару раз сталкивался с подобным при конвертировании документа ворд в формат pdf.

Наличие всех рисунков, чертежей, формул, таблиц

Наличие всех рисунков, чертежей, формул, таблиц проверяются по перечням, которые генерируются автоматически, см. pdf-версию статьи Улучшение навигации в бумажных документах.

Логический порядок частей внутри главы

О каких частях и главах идет речь? И о каком порядке? Главы и части глав ни ГОСТ 2.105, ни ГОСТ 19.106-78 не предусмотрены, предусмотрены разделы, подразделы, пункты, подпункты и перечисления, а логический их порядок регламентируется стандартами, определяющими требования к структуре (составу) и содержанию конкретных документов.

Наличие полного перечня документации

Для проверки полного перечня документации существуют ведомости.

Уровень языка общения пользователя с программой

Уровень языка общения пользователя с программой. Если тайный замысел разработчика ГОСТ 28195 понят автором правильно, то наивысшим уровнем языка взаимодействия пользователя с программой или техническими средствами является естественный для пользователя язык... Требование может быть сформулировано в подразделе Требования к лингвистическому обеспечению технического задания.

Возможность распечатки содержимого программы

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

Возможность приостанова и повторного запуска работы без потерь информации

Практически все прикладные программы периодически приостанавливаются, ожидая продолжения диалога с пользователем. Перестали набирать текст - Microsoft Word приостановился и ждет.

Большинство клиентов ftp при обрыве связи приостанавливаются, а при восстановлении связи продолжают скачку данных с точки приостанова, разумеется, без потерь.

Соответствие меню требованиям пользователя

Кто ж спросит пользователя, если он не является заказчиком или представителем заказчика? А вообще любые соотвествия проверяются при проведении испытаний приемочной комиссией, см. Достаточность документации для ввода ПС в эксплуатацию.

Возможность прямого перехода вверх и вниз по многоуровнему меню (пропуск уровней)

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

Перечень оценочных элементов фактора эффективности

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

Перечень оценочных элементов фактора универсальности

Рассмотрим несколько оценочных элементов фактора универсальности, применимых к технической документации (общее количество оценочных элементов фактора универсальности - 51).

Оценка числа потенциальных пользователей

Поскольку задача-минимум цикла статей О качестве... - охват программных документов, документов на СОИ и документации на автоматизированные системы, то под потенциальными пользователями следует понимать:

• пользователей программных средств;
• пользователей систем обработки информации;
• пользователей автоматизированных систем.

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

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

Насколько возможности программ охватывают область решаемых пользователем задач

Насколько возможности программ охватывают область решаемых пользователем задач - по аналогии с п. Оценка числа потенциальных пользователей. При разработке в интересах конкретного заказчика данный оценочный элемент бессмыслен: что прописали в требованиях технического задания на программу или АС, то и подтвердили результатами испытаний. Для всего прочего подойдут социологические методы:

Социологические методы основаны на обработке специальных анкет-вопросников [из п. 1.5.6 ГОСТ 28195-89]

Наличие схемы иерархии модулей программы

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

Оценка зависимости программ от емкости оперативной памяти ЭВМ

Оценка зависимости программ от емкости оперативной памяти ЭВМ: к объему оперативной памяти предъявляются требования в техническом задании, см. Требования к составу и параметрам технических средств. Таким образом, дело не в зависимости, а наличии требования (обязательного или альтернативного) в соотвествующем разделе ТЗ Требования к составу и параметрам технических средств. Оценочный элемент дублируется, см. Требуемый объем внутренней памяти.

Оценка зависимости функционирования программы от специальных устройств ввода-вывода

Оценка зависимости функционирования программы от специальных устройств ввода-вывода: все определяется техническим заданием. А устройств таких довольно много, перечисляем:

1. Устройство автоматического ввода графической информации по ГОСТ 25868-91;
2. Устройство ввода альтернативы (Choice device) по ГОСТ 27459-87;
3. Устройство ввода изолированной речи по ГОСТ 25868-91;
4. Устройство ввода печатного текста по ГОСТ 25868-91;
5. Устройство ввода позиций (Locator) по ГОСТ 27459-87;
6. Устройство ввода последовательности позиций (Stroke device) по ГОСТ 27459-87;
7. Устройство ввода речи по ГОСТ 25868-91;
8. Устройство ввода рукописного текста по ГОСТ 25868-91;
9. Устройство ввода штриховых кодов по ГОСТ 25868-91;
10. Устройство ввода-вывода аналоговых сигналов по ГОСТ 25868-91;
11. Алфавитно-цифровая клавиатура ввода данных по ГОСТ 25868-91;
12. Клавиатура ввода данных по ГОСТ 25868-91;
13. Функциональная клавиатура ввода данных по ГОСТ 25868-91;
14. Ввод-вывод данных с перфолент и перфокарт - это совсем уже из истории техники.

Комментарии к операторам объявления переменных

Комментарии к операторам объявления переменных: ужасно, когда переменная, константа, массив и т.д. объявлены, но не откомментированы. В тексте программы разобраться невозможно.

Перечень оценочных элементов фактора корректности

Рассмотрим несколько оценочных элементов фактора корректности, применимых к технической документации (общее количество оценочных элементов фактора корректности - 70).

Уже не успеваем, а было бы очень интересно. Придется переходить к результатам.

Результаты исследований

Краткие выводы

Собственно ГОСТ 28195 не является готовой методикой оценки качества, а представляет собой лишь некие общие положения, на основе которой и создается методика.

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

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

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

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

Сложность поиска соответствующих разделов документов для сопоставления их с оценочными элементами факторов

И все бы терпимо, но возникает вопрос: а где что искать? К какому разделу (подразделу, пункту, подпункту) можно приметить каждый конкретный оценочный элемент? Что с чем сопоставлять?

Рекомендации и исходные данные по конкретному использованию результатов исследования

Создание матрицы соотвествия разделов документов оценочным элементам методики

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

Оценка технико-экономической эффективности внедрения

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

Перспективы развития

Перспектива развития данной методики - привязка ее к автоматизированной системе технического документирования, разработанной нами в 2004 году - автоматизация экспертизы качества технической документации

Перечень источников

• Глаголев В. А. Разработка технической документации. Руководство для технических писателей и локализаторов ПО (+CD).- СПб.: Питер, 2008. -192 с.: ил.;
• Глаголев В. А. Управление качеством технической документации на промышленную продукцию;
• Цикл статей докладчика «Качество технической документации».