КомпанияУслугиОбучениеСервисы

Проект ГОСТа на стиль изложения

Версия для печати

Проект ГОСТа на стиль

Проект национального стандарта «Стиль изложения документации пользователя программного средства. Общие требования»

Кому и для чего нужен стандарт на стиль?

Стиль изложения — одно из наиболее сложно формализуемых качеств документации пользователя. Вместе с тем, любой читатель отличает плохо написанный текст от хорошо написанного. Если текст перегружен длинными сложно построенными фразами, в нем много неясностей, двусмысленностей, непоследовательно используется терминология, затруднен поиск нужных сведений, то работать с ним тяжело. Даже если содержание этого текста ценно, полезность его из-за трудности для восприятия сильно снижается. Как обеспечить в этом отношении качество документации пользователя? Не имея требований к стилю, мы можем уповать только на добродетели конкретного автора, на его старательность, опыт, вкус и литературные способности. При промышленном производстве программных продуктов такой подход слишком ненадежен. В случае совместной работы коллектива добросовестных и талантливых авторов над одним комплектом технической документации необходимо добиться от них если не полного единообразия, то хотя бы единства стиля изложения в его основных чертах. Встречная проблема заключается в том, что объективно хорошо написанный текст, функционально полностью соответствующий своим задачам, может просто не понравиться представителю заказчика, вызвать у него неприятие на уровне личного вкуса. Предлагаемый стандарт мыслится как инструмент для преодоления упомянутых затруднений и безболезненного урегулирования (а еще лучше, предотвращения) споров о качестве текста документации. Типичные, с нашей точки зрения, ситуации применения предлагаемого стандарта приведены ниже.

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

Текст проекта стандарта

Проект стандарта в формате PDF

Содержание проекта стандарта

1. Область применения
2. Нормативные ссылки
3. Термины и определения
4. Требования к стилю изложения и их обоснование
5. Правила структурированного изложения
5.1. Общие положения
5.2. Деление документа на структурные элементы
5.3. Раздельное расположение различных типов пользовательской 
     информации
5.4. Структурированное описание однородных объектов, действий, 
     процессов 
5.5. Структурированное описание действий пользователя в 
     пользовательском 
     интерфейсе
5.6. Деление текста на абзацы
5.7. Правила включения в текст иллюстраций, таблиц, формул и других 
     специализированных видов подачи информации
6. Правила строгого изложения
6.1. Общие положения
6.2. Употребление терминологии для обозначения специализированных 
     понятий
6.3. Употребление вспомогательных терминов
6.4. Употребление перифрастических, собирательных и обобщающих 
     наименований
6.5. Соблюдение необходимого уровня конкретности изложения
6.6. Соблюдение нейтрального стиля изложения
7. Правила единообразного изложения 
7.1. Общие положения
7.2. Единство терминологии
7.3. Единообразие в употреблении вспомогательных терминов
7.4. Последовательное употребление перифрастических, обобщающих 
     и собирательных наименований
7.5. Единообразие фрагментов текста, описывающих сходные явления
7.6. Особенности единообразного изложения
8. Правила детального изложения
8.1. Общие положения
8.2. Самодостаточность текста документации пользователя по отношению к 
     пользовательскому интерфейсу программного средства
8.3. Максимальная детализация действий пользователя в пользовательском 
     интерфейсе 
8.4. Точная идентификация объектов и элементов пользовательского 
     интерфейса
8.5. Пошаговое описание сложных действий
9. Правила однозначного изложения 
9.1. Общие положения
9.2. Однозначное описание действий, выполняемых лицами, 
     взаимодействующими с документируемым программным средством 
9.3. Однозначное описание действий, выполняемых программными 
     и аппаратными средствами
9.4. Упорядоченное употребление указательных местоимений и близких 
     к ним по значению слов и выражений
9.5. Исключение из употребления грамматических форм и синтаксических 
     конструкций, допускающих неоднозначную интерпретацию
10. Правила лаконичного изложения
10.1. Общие положения
10.2. Ограничения, накладываемые на структуру и размер предложений
10.3. Ограничения, накладываемые на содержание документации
11. Этикетные требования
11.1. Общие положения
11.2. Общие требования, предъявляемые к деятельности в сфере публичной 
      коммуникации
11.3. Нормы общения между поставщиком товаров и/или услуг 
      и их потребителем
11.4. Нормы общения между техническим специалистом и конечным 
      пользователем
Приложение А (рекомендуемое) Словарь вспомогательных терминов
Приложение Б (рекомендуемое) Перифрастические, собирательные 
             и обобщающие наименования
Приложение В (рекомендуемое) Указательные местоимения и близкие к ним 
             по значению слова 

   

© «Философт», 2008–2017

+7 (499) 500-44-77

mail@philosoft.ru

SpyLOG