Разработка документации пользователя
программного продукта. Методика и приемы

Даты: 05.10.10.

Длительность: 3 дня.

Макс. численность группы: 10 чел.

Модуль 1. Организация работы

Участники работы над документацией и их взаимодействие. Место технического писателя в современной IT-индустрии. Партнеры технического писателя на разных этапах его деятельности. Ориентация на пользователя: идеалы и действительность.

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

Сроки выполнения работы и их оценка. Проблема планирования сроков. Методы оценки сроков: поминутный/почасовой, нисходящего проектирования. Проблема соотношения сроков и качества работы. Различные схемы организации работы и их использование для оптимизации сроков. Основные факторы нарушения сроков и способы их преодоления.

Стандартизация документации. Постановка задачи стандартизации. Понятие стандарта. Мотивы использования стандартов. Виды стандартов: корпоративные, отраслевые, национальные, межгосударственные.

Проектирование стандарта. Состав стандарта: предписания и требования. Стандарты на продукцию и стандарты на процесс. Понятие профиля стандарта. Соблюдение стандарта. Понятие нормоконтроля.

Национальные стандарты и их особенности. Национальные стандарты в области технической документации. Единая система конструкторской документации (ГОСТ 2.xxx). Единая система программной документации (ГОСТ 19.xxx). Стандарты на разработку и сопровождение автоматизированных систем (ГОСТ 34.xxx). Область применения различных стандартов. Их совместное использование. Сильные и слабые стороны различных стандартов применительно к работе над пользовательской документацией.

Стандарты на процесс. ГОСТ Р ИСО/МЭК 15910-2002 'Процесс создания документации пользователя программного средства'. Обзор содержания стандарта.

Виды документов. Документы, создаваемые на различных этапах жизненного цикла программного средства. Понятие эксплуатационной документации и ее специфика. Стандарты ГОСТ 19.xxx и ГОСТ 34.xxx об эксплуатационной документации. Пользовательская документация как часть эксплуатационной документации. Стандарт ГОСТ Р ИСО/МЭК 15910-2002 о пользовательской документации. Стандарт IEEE 1063-2001.

Виды документов, входящих в состав эксплуатационной документации. Способы профилирования документов: по адресату, по характеру информации, по степени подробности. Тройной принцип.

Формирование комплекта документации. Понятие комплекта документации. Принципы формирования комплекта. Традиционный принцип формирования комплекта и концепция типичного пользователя. Функционально-ролевой принцип. Оформление документации в виде единого документа. Стандарты ГОСТ 19.xxx и ГОСТ 34.xxx о комплекте эксплуатационной документации.

Документ в составе комплекта документации. Связь между структурой (содержанием) документа и составом комплекта.

Модуль 2. Содержание документа и изложение материала

Проектирование структуры документа. Типовая структура. Степень детализации типовой структуры и ее пригодность для описания различных программных средств. Использование типовой структуры: преимущества и помехи.

Этапы проектирования структуры документа. Требования, предъявляемые к структуре документа. Логичность и последовательность изложения. Легкость поиска информации. Легкость запоминания и усвоения знаний о программном средстве. Дублирование информации в разных разделах документации. Структурные связи между разделами.

Расположение материала. Типы информации и их компоновка. Структурная информация и ее основные разновидности. Директивная информация и ее основные разновидности. Справочная информация и ее основные разновидности. Изложение с точки зрения пользователя. Изложение с точки зрения интерфейса (функциональной структуры) программы. Стандарт IEEE 1063-2001 о расположении материала и логике изложения.

Качество информации. Принцип условной самодостаточности текста. Требования к информации: достоверность, релевантность, понятность. Неверное или неточное описание. Понятие о тестировании документации. Неполное описание. Структурированное и неструктурированное описание объектов и функций.

Фигуры описания. Принцип унификации описания. Понятие фигуры описания. Стандартные формулы, заголовочные конструкции и грамматические модели. Вводные и вспомогательные конструкции. Описания объектов и отношений между ними. Процедуры, описания функций и практические рекомендации. Метатекст.

Попытки составления словаря фигур описания и связанные с этим проблемы. Microsoft Manual of Style о различных фигурах описания.

Сложные случаи описания объектов. Ветвящиеся процедуры и типовые функции. Длинные перечисления и способы их оформления. Проблема повторяющихся описаний. Многомерные объекты и зацикленные определения. Реальное и виртуальное: объекты, образы, идентификаторы. Наглядные и строгие описания, индуктивная и дедуктивная последовательности изложения. Антропоморфизм описаний: плюсы и минусы.

Лексика документации. Группы терминологии: предметная область, компьютер и его использование, элементы интерфейса. Согласование терминологии предметной области. Согласование компьютерной терминологии. Проблемы перевода англоязычной терминологии.

Вспомогательная лексика и ее унификация. Слова-артикли. Слова-классификаторы. Слова-прослойки.

Модуль 3. Язык и авторская разметка документа

Язык и стиль. Языковая культура и понимание. Объективное и субъективное в стилистике. Основные позиции самопроверки. Группы слов, не рекомендуемых к употреблению в документации.

Необходимость нормативного руководства по стилю технической документации. Иноязычные руководства: Microsoft Manual of Style, Style Guide from Sun Microsystems.

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

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

Основные виды авторской разметки текста. Понятие об авторской разметке текста. Заголовки, их языковая форма и способы их нумерации. Многошаговые процедуры, их оформление. Ненумерованные перечисления, их оформление. Врезки разного типа: замечания, рекомендации, предупреждения.

Иллюстрации, их разновидности. Особенности подготовки снимков фрагментов экрана ('скриншотов'). Подрисуночные подписи. Нумерация иллюстраций. Таблицы, их названия и нумерация.

Регламентация авторской разметки текста в национальных и отраслевых стандартах: ГОСТ 2.105, IEEE 1063-2001. Понятие шаблона.

Аппарат публикации. Понятие об аппарате публикации. Оглавление. Перекрестные ссылки. Указатель (индекс). Виды указателей. Методика составления предметного указателя. ГОСТ на указатели. Глоссарий.