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

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

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

«Мы стремились свести в единую систему всю совокупность типовых требований, которые должны, с нашей точки зрения, предъявляться к технической документации: руководствам, справочникам и т.д. При этом мы основывались на стандартах ГОСТ, стандартах компании 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?