Техническая документация программных продуктов Выполнил: студент группы П-201

Техническая документация программных продуктов Выполнил: студент группы П-201 Хаиров Ришат Проверил(а):Рыкунова Нэлли Витальевна

Определения Для начала нам понадобятся пара определений: Под программным обеспечением обычно понимается некоторая совокупность программных средств, предназначенных для решения определённого круга задач. Программный продукт - это конкретная программа или программный комплекс.

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

сценарии использования документации "Быстрый старт", т.е. поиск сведений об установке, настройке, запуске и начале работы с программным продуктом. Ознакомительное чтение для освоения продукта в целом, решения наиболее типичных задач. Целевой поиск путей решения той или иной задачи. Целевой запрос справочной информации по избранной функции или элементу интерфейса программы. Методическое освоение программного продукта, детальное знакомство со всеми нюансами его работы.

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

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

Заголовки Заголовки разделов документации не должны быть слишком длинными, должны иметь простую синтаксическую структуру (чтобы читаться "с одного взгляда"), должны сообщать необходимый минимум информации о содержании раздела, должны подчёркивать специфику содержания раздела по сравнению с другими, в особенности соседними разделами. Основные виды заголовков: Назывное предложение. Например, "Файлы и папки" или "Файлы с расширением .abc". Заголовок-вопрос. Например, "Как сделать то-то и то-то". "Назывные" заголовки наиболее удачны и употребительны в большинстве случаев. Если темой раздела является действие, то главным словом заголовка может стать отглагольное существительное (например, "Редактирование документа"). Отглагольные существительные являются относительно адекватной заменой герундия, употребительного в английских технических текстах.

Дублирование информации Отчасти дублирование информации осуществляется естественным порядком как результат изложения " в несколько обходов" . Дублирование информации в документации - это хорошее средство уменьшить потери информации при усвоении, а также облегчить поиск нужной информации (или вообще исключить необходимость такого поиска в некоторых ситуациях).

рекомендации Сведения "сквозного" характера следует давать один раз в подробном изложении, а в дальнейшем повторять только основные моменты. Следует использовать разные формы отсылки к уже изложенным сведениям: полное воспроизведение, сокращённое воспроизведение, ссылка. Следует всегда воспроизводить там, где это требуется, описания конкретных процедур. Реже - воспроизводить описания функций и возможностей. Ещё реже - воспроизводить концептуальные рассуждения.

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

группы лексики В технической документации можно выделить две большие группы лексики: Предметно-понятийная лексика. Лексика действий и отношений. Лексика Предметно-понятийная лексика Лексика действий и отношений

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