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

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

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

Когда умирает надежда, приходит отчаяние.

Мудрая латинская поговорка

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

Где взять структуру разделов руководства пользователя? С руководствами на изделия (руководство по эксплуатации по ГОСТ 2.601-95 ) и на автоматизированные системы (руководство пользователя по РД 50-34.698-90 ) все более или менее ясно. А вот сам документ «Руководство пользователя» программы в ГОСТах 19-й системы отсутствует как класс.

Каким содержимым наполнять разделы руководства пользователя? Как быть? Главное - не отчаиваться.

Вопросы, на которые должно дать ответы руководство пользователя

Подарите ребенку незнакомую ему электронную игрушку. Перечень вопросов будет примерно таким (если сразу же не разломает):

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

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

Цели и задачи статьи

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

Задачи:

    определить структуру разделов руководства пользователя; определить содержимое для заполнения разделов руководства пользователя.

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

Возможно, существуют и иные документы, но автору, основательно порывшемуся в рунетовской свалке, ничего более подходящего заполучить пока не удалось. Яндекс обнаружил в своих недрах еще одну страничку с названием «Как сделать хорошее руководство пользователя», автор которой именует себя на американЬ ский манер (типа John P. Morgan). Двухстраничное «наставление» с радостными возгласами было немедленно отправлено в корзину.

Манифест Кагарлицкого

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

(цитаты из манифеста Кагарлицкого)

Мы стремились свести в единую систему всю совокупность типовых требований, которые должны, с нашей точки зрения, предъявляться к технической документации: руководствам, справочникам и т.д. При этом мы основывались на стандартах(. )ГОСТ. стандартах компании Microsoft, опыте наших сотрудников и других разработчиков технической документации.

Начало хорошее.

В состав технической документации входят две стержневые части, которые мы будем называть соответственно руководством пользователя и справочником пользователя, или коротко: руководством и справочником (по аналогии с английскими словосочетаниями User's Guide и User's Reference). Они могут быть оформлены в виде отдельных документов (для крупных программных продуктов), а могут, напротив, существовать в интегрированном виде. Между ними даже может не быть четкой границы: единый текст способен совмещать в себе черты руководства и черты справочника.

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

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

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

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

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

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

Жаль. А так все хорошо начиналось. Со «стандартов ГОСТ» - «стандартов Государственных Стандартов » - простим г-на Кагарлицкого за тавтологию. Только вот решения первой задачи, поставленной автором настоящей статьи, в семидесятидвухстраничном манифесте (Arial'ом 12pt) нет. Уважаемый автор манифеста лишь поставилнам задачу. Что ж, нет пророка в своем отечестве. Может, есть пророк в отечестве буржуйском?

IEEE Std 1063-2001 «IEEE Standard for Software User Documentation»

Забугорный «пророческий» документ IEEE Std 1063-2001 (IEEE в простонародье - «ай-яй-яй») в подразделе 1.2 (Puprose) содержит такую строчку:

This revision provides requirements for the structure, information content, and format of both printed and electronic documentation.

В авторском понимании назначение (намерение, цель, замысел, стремление) документа IEEE Std 1063-2001 состоит в «обеспечении требований к структуре, информационному наполнению, форматированию (оформлению) как электронной, так и печатной пользовательской документации по программным средствам». Что ж, подходяще. Какую же структуру руководства пользователя предлагает IEEE Std 1063-2001?

Структура руководства пользователя по IEEE Std 1063-2001

Опциональная типовая структура руководства пользователя содержится в таблице из раздела Structure of software user documentation документа IEEE Std 1063-2001:

Источник: tdocs.su

Категория: Безопасность

Похожие статьи: