Выполнил студент группы П-201 Хаиров Ришат Проверил а Рыкунова

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

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

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

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

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

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

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

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

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

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

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

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

Далее - несколько рекомендаций по лексике действий и отношений. Не рекомендуется злоупотреблять сослагательным наклонением. Например, не рекомендуется писать: "Если бы вы хотели сохранить файл. . . ", лучше писать: "Если вы хотите сохранить файл. . . ". Совершенный и несовершенный виды глагола нужны не только для того, чтобы обозначать законченное и незаконченное действия. Несовершенный вид часто обозначает действие, совершаемое многократно, время от времени. Например, "Вы можете сохранить файлы. . . " и "Вы можете сохранять файлы. . . ". Правильный выбор глагола того или иного вида позволяет точнее формулировать мысли. Иногда родственные глаголы образуют целые "гнёзда", внутри которых различаются по способу действия. Например, "писать", "написать", "дописать", "переписать". Следует стараться использовать правильное слово в каждой ситуации. Активный залог применяется преимущественно для обозначения действий физических лиц, пассивный - для обозначений действий, выполняемых программой. Например: "Пользователь выполняет необходимые действия. . . ", но: "Все расчёты выполняются программой. . . ". Вообще, пассивным залогом не стоит злоупотреблять, т. к. он затрудняет восприятие текста. В изобилии встречающиеся прилагательные и причастия могут затруднять чтение, поэтому по возможности их следует заменять на глаголы или краткие прилагательные или причастия. Например: "Microsoft Word - это программный продукт, предназначенный для. . . и обладающий. . . " лучше заменить на: "Программный продукт Microsoft Word предназначен для. . . и обладает. . . ".

Текст документации должен отличаться высокой степенью формализации. Изложение должно быть по возможности единообразным. Формализация изложения позволяет пользователю быстро рассортировать информацию, с первого взгляда опознать знакомые или типичные действия, процедуры, проблемы и т. д. Формализация изложения начинается с унификации языка. Одинаковые объекты в документации называются одинаково. Одинаковые отношения между объектами описываются одинаковыми конструкциями. Разные объекты и отношения должны называться (описываться) по-разному.

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

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