Под программным обеспечением обычно понимается некоторая совокупность программных средств, предназначенных для решения определённого круга задач. Программный продукт - это конкретная программа или программный комплекс.
В состав технической документации как правило входят две основные части:
- Руководство пользователя (User's Guide), описание наиболее типичных пользовательских задач, ориентированное в основном на начинающих пользователей.
- Справочник пользователя (User's Reference), полное описание функциональности продукта.
Эти части могут существовать и в интегрированном виде.
Существует несколько сценариев использования документации пользователем:
- "Быстрый старт", т.е. поиск сведений об установке, настройке, запуске и начале работы с программным продуктом.
- Ознакомительное чтение для освоения продукта в целом, решения наиболее типичных задач.
- Целевой поиск путей решения той или иной задачи.
- Целевой запрос справочной информации по избранной функции или элементу интерфейса программы.
- Методическое освоение программного продукта, детальное знакомство со всеми нюансами его работы.
Пользователь вправе рассчитывать, что следуя любому из этих сценариев, он быстро сможет отыскать нужную ему информацию.
Общая логика изложения в документации сводится к следующему:
- Кратко описывается внешняя область, которую призван обслуживать программный продукт.
- Перечисляются типичные внешние задачи, которые могут решаться с использованием программного продукта.
- Устанавливается соответствие между внешними объектами и объектами, которыми оперирует программный продукт. Определяется, какие действия с внутренними объектами необходимо выполнить, чтобы решить те или иные внешние задачи.
- Даются исчерпывающие инструкции по выполнению конкретных процедур в программе.
- Даются необходимые пояснения к процедурам. Например, если описывается система, которая работает с регулярными выражениями, имеет смысл описать само понятие регулярных выражений и принципы работы с ними.
Недопустимо ставить цель и не указывать способ её достижения.
Недопустимо описывать способ достижения цели, не сформулировав самой
цели. Недопустимо смешивать внешние и внутренние объекты (например,
документ как таковой и файл документа).
Размещение сведений в технической документации определяется как общей
логикой изложения, так и соображениями удобства поиска информации. Чтобы
облегчить поиск информации, сильно не нарушив при этом общую логику
изложения, существует возможность разместить сведения относительно
независимыми группами, каждая из которых ориентирована на один или
несколько базовых сценариев использования документации (упомянутых
выше).
Размещение информации может выглядеть примерно так:
- Вводные главы - "быстрый старт".
- Руководство пользователя - ознакомительное чтение.
- Справочник пользователя - целевой поиск и целевые запросы, методическое освоение продукта.
- Специальные главы - дополнительная информация о сервисных функциях типа экспорта и импорта, поиска и т.п. Также относится к целевому поиску и целевым запросам, методическому освоению продукта.
Таким образом, сведения излагаются в несколько обходов: сначала
минимальные сведения о запуске, затем описание наиболее типичных задач,
затем подробный обзор всех функций. При этом при каждом следующем обходе
даётся более полный обзор возможностей.
Заголовки разделов документации не должны быть слишком длинными,
должны иметь простую синтаксическую структуру (чтобы читаться "с одного
взгляда"), должны сообщать необходимый минимум информации о содержании
раздела, должны подчёркивать специфику содержания раздела по сравнению с
другими, в особенности соседними разделами.
Основные виды заголовков:
- Назывное предложение. Например, "Файлы и папки" или "Файлы с расширением .abc".
- Заголовок-вопрос. Например, "Как сделать то-то и то-то".
"Назывные" заголовки наиболее удачны и употребительны в большинстве
случаев. Если темой раздела является действие, то главным словом
заголовка может стать отглагольное существительное (например,
"Редактирование документа"). Отглагольные существительные являются
относительно адекватной заменой герундия, употребительного в английских
технических текстах.
Дублирование информации в документации - это хорошее средство
уменьшить потери информации при усвоении, а также облегчить поиск нужной
информации (или вообще исключить необходимость такого поиска в
некоторых ситуациях).
Отчасти дублирование информации осуществляется естественным порядком как результат изложения "в несколько обходов" (см. выше).
В то же время дублирование информации может затруднять поиск нужных тем, а также создание индекса, системы ссылок и т.п.
Несколько рекомендаций:
- Сведения "сквозного" характера следует давать один раз в подробном изложении, а в дальнейшем повторять только основные моменты.
- Следует использовать разные формы отсылки к уже изложенным сведениям: полное воспроизведение, сокращённое воспроизведение, ссылка.
- Следует всегда воспроизводить там, где это требуется, описания конкретных процедур. Реже - воспроизводить описания функций и возможностей. Ещё реже - воспроизводить концептуальные рассуждения.
Текст документации состоит из основного текста, на фоне которого обособляются выделенные сведения.
К выделенным сообщениям относятся:
- Инструкции или описания процедур. Располагаются непосредственно после сведений, относящихся к более общим уровням описания продукта. Т.е. сначала - разъяснение, чего можно добиться, каков смысл тех или иных функций и возможностей, а затем - описание конкретной процедуры.
- Определения. Даются перед или сразу после первого упоминания термина. Термину может быть дано и неявное (прямо в основном тексте) определение.
- Советы и замечания.
- Предупреждения. Располагаются непосредственно перед описанием того действия, которое может оказаться опасным.
К выделенным элементам относятся:
- Вновь вводимые термины.
- Фрагменты экранного текста или кода.
- Названия элементов интерфейса.
- Названия клавиш и их комбинаций.
Удобно, когда тема сначала конспективно разбита на основные "опорные
точки", пункты, а затем изложена подробно - поочерёдно по каждому из
пунктов. Это удобно и для запоминания, и для систематического усвоения.
Пункты перечисления даются в виде списка с символами бюллетеня (жирными
точками).
В технической документации можно выделить две большие группы лексики:
- Предметно-понятийная лексика.
- Лексика действий и отношений.
Предметно-понятийная лексика включает в себя несколько основных групп:
- Терминология внешней области, которую обслуживает программный продукт.
- Компьютерная терминология.
- Специфическая терминология данного программного продукта.
- Наименования участников рабочего процесса (пользователи, администраторы и т.д.).
- Характеризующие слова ("имя", "название", "число", "количество", "параметр", "свойство", "атрибут"). Слово "параметр" относится только к численным характеристикам объекта. Слово "свойство" - как к численным, так и не выражаемым числом. Слово "атрибут" обозначает не просто свойство, а неотъемлемую часть объекта.
- Слова-"прослойки". Например, нельзя сказать: "изменить переменную", но надо: "изменить значение переменной". Нельзя сказать: "задать действие с объектами", но надо: "задать вид действия с объектами". Нельзя сказать: "Создать контрагента", но надо: "Создать запись о контрагенте".
Далее - несколько рекомендаций по лексике действий и отношений.
Не рекомендуется злоупотреблять сослагательным наклонением. Например, не
рекомендуется писать: "Если бы вы хотели сохранить файл...", лучше
писать: "Если вы хотите сохранить файл...".
Совершенный и несовершенный виды глагола нужны не только для того, чтобы
обозначать законченное и незаконченное действия. Несовершенный вид
часто обозначает действие, совершаемое многократно, время от времени.
Например, "Вы можете сохранить файлы..." и "Вы можете сохранять
файлы...". Правильный выбор глагола того или иного вида позволяет точнее
формулировать мысли.
Иногда родственные глаголы образуют целые "гнёзда", внутри которых
различаются по способу действия. Например, "писать", "написать",
"дописать", "переписать". Следует стараться использовать правильное
слово в каждой ситуации.
Активный залог применяется преимущественно для обозначения действий
физических лиц, пассивный - для обозначений действий, выполняемых
программой. Например: "Пользователь выполняет необходимые действия...",
но: "Все расчёты выполняются программой...". Вообще, пассивным залогом
не стоит злоупотреблять, т.к. он затрудняет восприятие текста.
В изобилии встречающиеся прилагательные и причастия могут затруднять
чтение, поэтому по возможности их следует заменять на глаголы или
краткие прилагательные или причастия. Например: "Microsoft Word - это
программный продукт, предназначенный для... и обладающий..." лучше
заменить на: "Программный продукт Microsoft Word предназначен для... и
обладает...".
В английском языке существует особая неличная форма глагола - герундий. В
русском языке многие глаголы допускают образование отглагольных
существительных, которые являются относительно адекватной заменой
герундия. Наиболее распространённая модель образования отглагольных
существительных предполагает возникновение нового слова, оканчивающегося
на -ние. Например: "редактировать" - "редактирование". Однако,
существуют и другие модели, о которых следует помнить, чтобы не
порождать монстров вроде: "устанавливание" (установка), "захватывание"
(захват), "демонстрирование" (демонстрация) и т.п.
Конструкции типа "выполнить установку" являются заменами глаголов
("установить"). Они употребляются, когда необходимо одним
словосочетанием обозначить многошаговую процедуру. Не стоит, к примеру,
писать: "Выполнить создание файла". Вообще, следует избегать
употребления существительных для обозначения действий, т.к. это делает
изложение менее внятным и утяжеляет синтаксис, делая его похожим на
бюрократические штампы.
Текст документации должен отличаться высокой степенью формализации.
Изложение должно быть по возможности единообразным. Формализация
изложения позволяет пользователю быстро рассортировать информацию, с
первого взгляда опознать знакомые или типичные действия, процедуры,
проблемы и т.д.
Формализация изложения начинается с унификации языка. Одинаковые
объекты в документации называются одинаково. Одинаковые отношения между
объектами описываются одинаковыми конструкциями. Разные объекты и
отношения должны называться (описываться) по-разному.
У всякого термина существует своя околотерминологическая среда,
которая также должна быть унифицирована. Например, у термина "файл"
существует следующая околотерминологическая среда: "создать", "удалить",
"переименовать", "копировать" и т.д. У термина "кнопка" эта среда
состоит из одного слова: "нажать на". При этом важно, что надо писать
"нажать на кнопку", но не "нажать кнопку". Также нельзя "щёлкнуть по
кнопке мышью".
Существует целый ряд процедур, фрагментов интерфейса и т.д., которые
встречаются при работе со многими программными продуктами. Рекомендуется
пользоваться разработанными для подобных ситуаций клише.
Порядок слов является дополнительным средством передачи информации. Инверсией в расположении членов предложения считается отклонение от так называемого прямого порядка слов.
При прямом порядке слов сказуемое следует после подлежащего, а прямое
дополнение следует после сказуемого (кто - делает - что). Зависимое
слово желательно располагать вплотную к главному, во всяком случае как
можно ближе к нему. Инверсия порядка слов порождает довольно резкую эмфазу
- смысловое ударение на каком-то из членов предложения. Инверсию в
технической документации лучше избегать, т.к. инверсия делает текст
излишне экспрессивным или чересчур "разговорным". Для выражения эмфазы
лучше применять другие средства, например усилительные частицы "именно",
"же" и т.д.
Содержание предложения членится на тему и рему. Тема - это
то, что известно заранее, задано всем предшествующим контекстом. Рема -
это то, что в предложении сообщается нового и актуального. В
предложении не может не быть ремы, но может не быть темы. Предложения,
состоящие из одной только ремы, весьма употребительны в художественной
литературе, но в технической документации подавляющее большинство фраз
состоят из темы и ремы. Кроме того, существует общее правило: тема
предшествует реме. Расположение темы и ремы в таком порядке является
признаком нейтрального, не окрашенного экспрессией стиля.
Техническая документация допускает более частое, чем обычный литературный текст, повторение
отдельных слов и выражений. Рекомендуется, допуская такие повторы,
подчёркивать каждый раз, что повтор является намеренным. Например,
вместо: "Вы можете изменять значения параметров настройки. Значения
параметров настройки содержатся в файле настройки" можно написать: "Вы
можете изменять значения параметров настройки. Эти значения содержатся в
особом файле, который называется файлом настройки".
Усложнённый синтаксис делает документацию труднодоступной. Необходимо бороться с конструкциями, которые не являются оптимальными для восприятия:
- Разбивать слишком длинные предложения на два или три.
- По возможности избавляться от причастных и деепричастных оборотов, а также придаточных предложений со словом "который".
- Не допускать, чтобы между причастным оборотом (или придаточным-определительным) и определяемым словом вклинивались какие-то ещё слова.
- Избегать местоимений, которые отсылают к предыдущей фразе.
- Избегать паразитных конструкций вроде "в ходе функционирования" и т.п.
- Избегать нанизывания родительных падежей, повторного (в рамках одной фразы) употребления союзов и предлогов.
Комментариев нет:
Отправить комментарий