Как писать руководство пользователя? Часть II

Как писать руководство пользователя? Часть II

Пуркуа бы да не па?

Та самая смесь

Почему бы нет? Взять лучшее из ГОСТ 19, - обобщенную структуру руководства пользователя, добавить к ней немногочисленные толковые рекомендации из IEEE Std 1063-2001 и разбавить неисчерпаемой стилистической культурой и ресурсами языка из манифеста Кагарлицкого? Придать смеси стройный строгий вид, сформировать очередной учебно-тренировочный документ с подробными комментариями? А что делать, если ни один из перечисленных выше источников и составных частей в отдельности не способны дать ответы на все поставленные вопросы?

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

Цели и задачи

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

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

Разъяснения к задачам

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

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

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

- Поручик, Вы любите детей?

- Никак нет-с. Но сам процесс...

Как ни прискорбно, но задача освещения процессов (процедур) разработки технической документации в первой части статьи не ставилась. Ибо о процессах имеется отдельная статья - «Автоматизация разработки технической документации. Часть I».

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

Именно из этих соображений освещать в статье процессы внутренней кухни не имеет смысла.

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

В чем же причина отсутствия интереса к структуре руководства пользователя? Вероятно, многие г-да технические писатели считают, что:

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

Так ли это? Для уточнения приоритетов следует вернуться к манифесту, а затем рассмотреть реальные образцы структур руководств пользователей.

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

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

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

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

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

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

Вот она, забота о пользователе! Структура разделов руководства пользователя является определяющей при разработке пользовательских руководств.

Автор манифеста решил задачу по-своему, не ссылаясь на ГОСТ 19 и IEEE Std 1063-2001 - альтернативным способом. Важно совпадение результатов. А не как у Незнайки - сколько вариантов решения, столько и вариантов ответов.

Руководство пользователя: обосновано ли отсутствие интереса технических писателей к структуре разделов?

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

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

Структуры руководств пользователей - пример получше

На рисунке - структуры заголовков 1 уровня руководств пользователя двух равноуровневых «подсистем» единого программного комплекса.

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

Структура руководства пользователя - пример похуже

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

Простые формальные замечания:

• Предисловие расположено после Оглавления;
• Предисловие (по сути - Введение) - заголовок 1 уровня, Заключение - заголовок 2 уровня;
• Гиперссылки не имеют никакого отношения к Навигации и существуют сами по себе;
• разделы Отличия от предыдущей версии и Что нового (в нынешней версии по сравнению с предыдущей), призванные нести единую смысловую нагрузку, не объединены и живут каждый своей жизнью;
• Учет запчастей и ремонтов явно не входит в Задачи автотранспортной компании (интересно, кто же должен заниматься учетом запчастей и ремонтов?);
• по непонятным причинам часть заголовков разделов оцифрована, большая часть - нет.

Выводы

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

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

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

С одной стороны, по мнению автора образца,

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

Автор образца не знаком с п. 1 ст. 10. Закона «О защите прав потребителей» - «Изготовитель (исполнитель, продавец) обязан своевременно предоставлять потребителю необходимую и достоверную информацию о товарах (работах, услугах), обеспечивающую возможность их правильного выбора».

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

Формальные замечания:

• «Если навести...» - ух, каков стиль! Без старого наводчика Циреса, которого «завалил» Беня Крик, пользователю никак не обойтись;
• служил участок гиперссылкой (служил Гаврила хлебопеком);
• указатели чудесным образом превращаются в «персты» («пятерни», «лапы»). А брюки - в элегантные шорты;
• гиперссылки, как выясняется, бывают «выполненными» и позволяют бродить по чьим-то участкам;
• при отсутствии участка гиперссылка не работает (разумеется).

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

А что скажут медики? «... указанные симптомы в течение длительного времени наблюдались лечащим врачом у больного К., 56 лет». Медицинская этика всегда была и остается на высоте. Дабы не выходить из этических рамок, идентифицировать технических писателей всех времен и народов будем на медицинский манер - одной заглавной буквой.

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

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

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

«Фермером родился - простофилей умрешь»

Энди Таккер, Бендер Заокеанский

Из манифеста:

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

Автор манифеста утверждает, что каждое (вновь разрабатываемое) программное изделие обладает уникальнейшими, свойственными исключительно ему, программному изделию, параметрами, характеристиками, функциональными возможностями, которые принципиально невозможно разбросать по типовой структуре разделов. Какие новые реалии автор манифеста не в силах втиснуть в «ячейки» типовой структуры? Сформировавшийся за последние пятнадцать лет графический пользовательский интерфейс? Да запросто. См. «Как писать руководство оператора по ГОСТ 19.505-79?»

Заглянем в будущее. Наша оборонка придумала (а буржуи украли) бесконтактный пользовательский интерфейс. По типу терменвокса.

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

Так вот, возможно ли втиснуть описание бесконтактного пользовательского «терменфейса» в типовые ячейки структуры? Без особых проблем. Фрагмент руководства из будущего: «...для печати документа следует сложить пальцы фигой» (изображения «лап» и «перстов» из «руководств» окажутся весьма кстати).

Программа родилась программой - программой и умрет (завершит свой жизненный цикл). Какими бы голографическими пользовательскими интерфейсами программу ни оснащали.

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

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

• для конкретного заказчика (З);
• для «дома и офиса» - для пользователя (П).

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

• Н - раздел настоятельно рекомендуется;
• Р - раздел рекомендуется;
• О - раздел опционален.

Почему такое зверство? А есть п. 3 ст. 10 ФЗ «О защите прав потребителей» - «...исчерпывающая информация о товаре доводится изготовителем до сведения потребителя в технической документации, прилагаемой к товарам...». А программа - это ведь народно-хозяйственная продукция (для пользователя-потребителя) и продукция производственно-технического назначения (для заказчика).

Руководство пользователя: избавление от «старообразности» заголовков разделов

Указанная задача также требует разъяснений, поскольку один и тот же заголовок раздела руководства пользователя, структура которого (в целом) сформирована в первой части статьи, может трактоваться неоднозначно или попросту вызывать недоумение. К примеру, раздел «Входные точки в программу».

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

Компромиссный вариант структуры руководства пользователя должен устраивать «и наших, и ваших»:

• «наших» - удовлетворять требованиям стандартов 19-й системы (и здравого смысла);
• «ваших», включая:
  • рекомендации IEEE Std 1063-2001 (для любителей всего «заграничненького»);
  • рекомендации манифеста Кагарлицкого (для любителей изящного, изысканного построения фраз);
  • фантазии «технических писателей всех времен и народов», коим техническая документация, разработанная согласно требований «увесистого тома ГОСТ 19», кажется «составленной непонятно и дурно».

Компромиссный вариант, по мере его формирования (в табличке), и предлагается к обсуждению.

Компромиссный вариант структуры разделов руководства пользователя

Цифры 1, 2 и т.д. соответствуют уровню вложенности заголовка.

Введение

По ГОСТ 19 раздел старообразно называется Аннотацией. Пусть будет Введением. Противоречий с IEEE Std 1063-2001 нет, поскольку имеет место Introduction.

Назначение документа

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

Что писать - ясно.

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

Краткое изложение основной части документа

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

В пользовательском документе можно было бы «объединить» текущий подраздел с предыдущим (при публикации), спрятав заголовок подраздела.

Общие сведения о программе

В IEEE Std 1063-2001 соотвествует разделу Scope. Можно назвать Обзором.

Обозначение и наименование программы

Наименование программы - «Автоматизированный программный комплекс разработки технической документации». Обозначение программы - FineDeveloper™.

Языки программирования, на которых написана программа

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

Назначение программы

Программа FineDeveloper™ предназначена для автоматизации разработки техдокументации в строгом соответствии требованиям отечественных и зарубежных стандартов.

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

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

Возможности программы

Информация, достаточная для понимания функций программы и ее эксплуатации.

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

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

Классы решаемых задач

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

Описание задач

Следует исходить из возможностей, если техническое задание по ГОСТ 19.201-78 отсутствует. А задача программы FineDeveloper™ такова:

• имеется техническая информация;
• имеется нормативно-техническая документация (ГОСТы, IEEE и пр.);
• техническая информация и нормативно-техническая документация тем или иным способом «скармливаются» программе;
• а программа должна дать на выходе комплект технической документации на заданных языках с учетом требований НТД.

Методы решения задач

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

Пользователю вряд ли интересно расписывать методы решения задач - сам знает, как их решать. А вот заказчик может заинтересоваться.

Функции, выполняемые программой

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

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

Описание основных характеристик и особенностей программы

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

Разъясним сказанное словами. Разгоняем проектный отдел, разгоняем все четыре бригады технических писателей. Сажаем девочку с улицы на двухсотдолларовую зарплату. Девочка тупо скармливает программе материалы, предоставленные кодировщиками, а на выходе - документация. Вот как издержки снижать надо! Инновациями, а не тупым «эффективным менеджментом»...

ВременнЫе характеристики

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

Режим работы

Круглосуточный непрерывный. Штатный, аварийный, сервисный - исходя из техзадания или проектной документации.

Нет технического задания - придумаем свои режимы:

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

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

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

Примечание от 27.01.2012 - Очень много интересного по этому поводу есть в цикле статей «Качество технической документации».

Ограничения области применения программы

Показать надо обязательно. Ибо ФЗ «О защите прав потребителей» худо-бедно работает. Программа не может и не должна делать то, для чего не предназначена.

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

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

Условия применения программы

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

Условия, необходимые для выполнения программы

А вот при температуре от плюс 5 до плюс 35 °C будет (при разумной влажности воздуха). Следует указать.

Сведения о технических и программных средствах, обеспечивающих выполнение программы

Как минимум, потребуются:

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

Для начала достаточно простого перечня. Дальше - ширше.

Требования к техническим средствам

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

Раздел очень важный. Приобрел пользователь программу, а она у него на i386 не запускается. Сразу обоснованные претензии, если раздел отсутствует.

Виды ЭВМ, устройств, используемых программой

IBM PC или Mac, с такой-то внутренней начинкой:

• процессором не хуже...;
• с объемом оперативной памяти не менее...;
• с жестким диском объемом не менее...;
• звуковой картой не хуже;
• сетевой картой такой-то;
• и так далее.

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

Минимальный состав технических средств

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

Требования к составу и параметрам периферийных устройств

Перечень и краткое описание.

Перечень:

• принтер такой-то;
• сканер такой-то;
• и т.д.

Краткое описание.

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

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

Здесь перечень общего и специального программного обеспечения... ГОСТ 34 круче 19-го, как ни крути

Требования к программному обеспечению

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

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

Требования к другим программам

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

Требования и условия организационного, технического и технологического характера

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

«Предварительное Заключение»

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

Примечание от 27.01.2012 - Так и вызревает с 18.02.2005

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

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

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