Компромиссный вариант структуры разделов руководства пользователя
Цифры 1, 2 и т.д. соответствуют уровню вложенности заголовка.
Наименование раздела (подраздела)
|
П
|
З
|
(1) Введение
|
Н
|
Н
|
(2) Назначение документа
|
Р
|
Н
|
(2) Краткое изложение основной части документа
|
Р
|
Н
|
(1) Общие сведения о программе
|
Р
|
Н
|
(2) Обозначение и наименование программы
|
О
|
Н
|
(2) Языки программирования, на которых написана программа
|
О
|
О
|
(2) Назначение программы
|
Р
|
Н
|
(2) Возможности программы
|
Р
|
Н
|
(3) Классы решаемых задач
|
О
|
О
|
(3-4) Описание задач
|
Р
|
Н
|
(3-4) Методы решения задач
|
О
|
Р
|
(3) Функции, выполняемые программой
|
Н
|
Н
|
(2) Описание основных характеристик и особенностей программы
|
Н
|
Н
|
(3) Временные характеристики
|
Р
|
Н
|
(3) Режим работы
|
О
|
Н
|
(3) Средства контроля правильности выполнения и самовосстанавливаемости программы
|
Н
|
Н
|
(2) Ограничения области применения программы
|
Н
|
Н
|
(3) Сведения о функциональных ограничениях на применение
|
Н
|
Н
|
(1) Условия применения программы
|
Н
|
Н
|
(2) Условия, необходимые для выполнения программы
|
Н
|
Н
|
(3) Сведения о технических и программных средствах, обеспечивающих выполнение программы
|
Н
|
Н
|
(3) Требования к техническим средствам
|
Н
|
Н
|
(4) Виды ЭВМ, устройств, используемых программой
|
Н
|
Н
|
(4) Минимальный состав технических средств
|
Н
|
Н
|
(4) Требования к составу и параметрам периферийных устройств
|
Н
|
Н
|
(3) Программное обеспечение, необходимое для функционирования программы
|
Н
|
Н
|
(4) Требования к программному обеспечению
|
Н
|
Н
|
(4) Требования к другим программам
|
Н
|
Н
|
(3) Требования и условия организационного, технического и технологического характера
|
Н
|
Н
|
Введение
В разделе:
Назначение документа
Краткое изложение основной части документа
|
По ГОСТ 19 раздел старообразно называется Аннотацией. Пусть будет Введением. Противоречий с IEEE Std 1063-2001 нет, поскольку имеет место Introduction.
Назначение документа
Настоящее руководство предназначено для ознакомления пользователя с техническими характеристиками и функциональными возможностями программы FineDeveloper™ и так далее. Что писать - ясно.
Кому не нравится Назначение документа, может обозвать раздел как Назначение руководства. Дело вкуса. Только чтобы раз и навсегда, во всех документах компании раздел так и назывался.
Краткое изложение основной части документа
В основной части документа приведены сведения о назначении программы, об условиях применения программы, о логической структуре программы, о входных и выходных данных, используемых программой, а также сведения о настройке, проверке, выполнении программой своих функций, сведения о дополнительных возможностях программы и сведения о сообщениях, формируемых программой.
В пользовательском документе можно было бы «объединить» с предыдущим при публикации, спрятав заголовок подраздела.
Общие сведения о программе
В IEEE Std 1063-2001 соотвествует разделу Scope. Можно назвать Обзором.
Обозначение и наименование программы
Наименование программы - «Автоматизированный программный комплекс разработки технической документации».
Обозначение программы - FineDeveloper™.
Языки программирования, на которых написана программа
Раздел на усмотрение Заказчика.
Назначение программы
Программа FineDeveloper™ предназначена для автоматизации разработки технической документации в строгом соответствии требованиям отечественных и зарубежных стандартов.
Примечание. Заголовок может показаться любителям изящной словесности канцелярски-формальным и тяжелым для восприятия. Нет ничего невозможного - пожалуйста:
Без всякого сомнения, альтернативный вариант заголовка менее формален, более точно и доходчиво отражает суть содержимого раздела.
Возможности программы
Информация, достаточная для понимания функций программы и ее эксплуатации.
Программа обеспечивает возможность автоматической разработки и публикации технической документации согласно требованиям любых отечественных и зарубежных стандартов на всех языках народов мира.
Классы решаемых задач
Классифицировать решаемые задачи способен только Заказчик. А если неспособен, тогда уровни вложенных подразделов стоит обозначить не 4, а 3.
Описание задач
Следует исходить из возможностей, если техническое задание на программу отсутствует. А задача программы FineDeveloper™ такова:
имеется техническая информация;
имеется нормативно-техническая документация (ГОСТы, IEEE и пр.);
техническая информация и нормативно-техническая документация тем или иным способом «скармливаются» программе;
а программа должна дать на выходе комплект технической документации на заданных языках с учетом требований НТД.
Методы решения задач
Задача решается методом последовательных приближений с использованием сверхмощного синтаксического (лингвистического и т.д.) анализатора нового поколения на основе использования нейросетевых технологий извлечения и понимания контекста, являющегося запатентованной разработкой отечественной оборонки.
Пользователю вряд ли интересны методы решения задач. А вот Заказчик может заинтересоваться.
Функции, выполняемые программой
Это святое. Какой толк от руководства, если пользователь не может понять, что же делает программа.
Поскольку раздел самого общего плана (Общие сведения о программе), достаточно просто дать в нем перечень функций без подробного их описания.
Описание основных характеристик и особенностей программы
Очень полезный раздел. Особенность программы FineDeveloper заключается в том, что программа в очень короткое время способна «прожевать» оргомное количество исходного материала любого формата и выдать техническую документацию мирового уровня качества.
Разъясним сказанное словами. Разгоняем проектный отдел, разгоняем все четыре бригады технических писателей. Сажаем девочку с улицы на двухсотдолларовую зарплату. Девочка тупо скармливает программе материалы, предоставленные программерами, а на выходе - документация. Вот как издержки снижать надо.
Временные характеристики
В самый раз показать временные характеристики. Если проектировщики и техписы выпускают техническую документацию за месяц (да еще и кривую), программа справляется за полдня (и с «неземным» качеством).
Режим работы
Круглосуточный непрерывный. Штатный, аварийный, сервисный - исходя из технического задания или проектной документации.
Нет технического задания - придумаем свои режимы:
режим получения и обработки поступающей информации;
режим формирования технической документации;
режим локализации технической документации;
режим публикации технической документации.
Средства контроля правильности выполнения и самовосстанавливаемости программы
Если таковые имеются, следует рассказать о них всем. Если нет, лучше не показывать заголовок при публикации документа.
Ограничения области применения программы
Показать надо обязательно. Ибо Закон «О защите прав потребителей» имеется. Программа не может и не должна делать то, к чему не предназначена.
Сведения о функциональных ограничениях на применение
Если программа не в состоянии выполнять функции сочинения стихотворений на основе исходных художественных материалов, стоит об этом заявить прямо. Во избежание претензий.
Условия применения программы
Обязательно. Не будет программа выполняться на ноутбуке при пятидесятиградусном морозе.
Условия, необходимые для выполнения программы
А вот при температуре от плюс 5 до плюс 35 °C будет. Следует указать.
Сведения о технических и программных средствах, обеспечивающих выполнение программы
Как минимум, потребуются:
компьютер;
принтер;
сканер;
дигитайзер;
операционная система;
прикладные и сервисные программные средства;
и все такое.
Для начала достаточно простого перечня. Дальше - ширше.
Требования к техническим средствам
Имеет смысл оставить без текста, просто заголовком, разделяющим средства технические и средства программные. Так нагляднее, упрощается поиск по Содержанию.
Раздел очень важный. Приобрел пользователь программу, а она у него на i386 не запускается. Сразу обоснованные претензии, если раздел отсутствует.
Виды ЭВМ, устройств, используемых программой
IBM PC или Mac, с такой-то внутренней начинкой:
процессором не хуже...;
с объемом оперативной памяти не менее...;
с жестким диском объемом не менее...;
звуковой картой не хуже;
сетевой картой такой-то;
и так далее.
Пусть подраздел освещает рекомендуемый состав технических средств. Можно так его и обозвать.
Минимальный состав технических средств
А здесь может быть тот же перечень, только по предельно-допустимому минимуму требований.
Требования к составу и параметрам периферийных устройств
Перечень и краткое описание.
Перечень:
принтер такой-то;
сканер такой-то;
и т.д.
Краткое описание.
Принтер такой-то необходим из-за того, что другие принтеры не обладают такими-то характеристиками.
Сканер такой-то необходим из-за того, что у других сканеров маловато разрешение или узковата область сканирования.
И так далее.
Программное обеспечение, необходимое для функционирования программы
Здесь перечень системных, специальных и прикладных программных средств.
Требования к программному обеспечению
Сначала требования к системным программным средствам - должна быть такая-то операционная система.
Затем требования к специальным программным средствам - должны быть драйверы принтера, сканера и т.д.
Требования к другим программам
Требования к прикладным программным средствам - должен быть почтовый клиент, без которого программа не сможет отправлять/получать почтовые сообщения.
Требования и условия организационного, технического и технологического характера
Чтобы программа полноценно выполняла свои функции, потребуется прокладка локальной сети, организация доступа в Интернет и так далее.
«Предварительное Заключение»
К сожалению, закончить статью в сжатые сроки не удается, а сбрасывать информацию в третью часть статьи нелогично. Пусть статья считается версией первой II части и полежит на сайте до ближайших выходных. Может, вопросов по-существу прибавится.
Кое-кто может возмутиться - мыслимо ли выкладывать на всеобщее обозрения «полусырую» версию статьи? А почему нет? Ведь выкладывают же некоторые технические писатели окончательные варианты «руководств», - полнейшее сырье, подлежащее переработке с нуля? И ничего, все сходит им с рук.
В учебно-тренировочных документах рассмотрено наполнение разделов руководства оператора. Непонятно по конкретному разделу - задавайте вопросы в форуме.
|
