Теоретический раздел документа
Теоретический раздел — один из начальных разделов технического документа. В этом разделе авторы вводят понятия, необходимые читателю для освоения дальнейшего материала, дают определения наиболее важных терминов, описывают модель предметной области, заложенную в техническое решение, которому посвящен документ. Ознакомившись с теоретическим разделом, читатель должен ясно осознать, насколько эта модель полна и точна, какие явления предметной области она отражает, и что представляют собой их «цифровые двойники». Побочная, но важная задача такого раздела — создание удобных языковых средств, которые упростят автору написание, а читателю восприятие основного содержания документа. В дополнение к базовым терминам туда входят термины вспомогательные, сопутствующая лексика, фигуры описания. Удачный теоретический раздел образует смысловой каркас технического текста, посвященного сколько-нибудь небанальному предмету. Он делает текст понятным, не позволяя ему стать нагромождением разрозненных утверждений. В простейшем случае теоретический раздел документа сводят к словарю его терминологии.
Содержание теоретического раздела
Основные темы теоретического раздела технического документа, как правило, таковы:
- модель предметной области, заложенная в описываемое техническое решение;
- принципы функционирования, порядок использования этого решения;
- соглашения о терминах, сопутствующей лексике и прочих условностях.
Предметная область
Точка зрения на предметную область
Любое решение в сфере информационных технологий, если оно не совсем утилитарно, предназначено для работы в некоторой предметной области. По отношению к самим информационным технологиям эта область может быть как внешней, так и внутренней. Например, для авиасимулятора предметной областью будет управление летательным аппаратом, а для системы резервного копирования данных — само резервное копирование. Наконец, можно привести примеры систем, порождающих собственные предметные области: таковы социальные сети или игры со сложными игровыми мирами.
Ни одно техническое решение не отражает свою предметную область во всех подробностях, поскольку это невозможно, да и ненужно. Реальность всегда подменяют ее информационной или математической моделью, требования к точности которой зависят от поставленных задач. Техническая реализация этой модели выражается в конкретных средствах, из которых это решение состоит. Образно говоря, получаются три смысловых слоя или среза, проходящих через каждое явление предметной области.
Полноценное использование, тем более создание программного продукта или системы требует сквозного понимания всех трех слоев. Такое понимание должен создать у читателя теоретический раздел, в материале которого можно выделить две крупные темы:
- объекты предметной области, попадающие в «поле зрения» системы;
- процессы, протекающие в системе с образами этих объектов.
Объекты предметной области
Объекты предметной области, значимые для описываемого технического решения, необходимо перечислить и поименовать. Хороший способ решить эту задачу — привести определения терминов, которыми они будут обозначены в документе. Затем появляется возможность привести для каждого объекта описание модели и средств его представления в системе. Условно говоря, есть воздух в комнате, есть описанный в учебниках физики идеальный газ, а есть виртуальный объем газа, поведение которого симулирует некоторая вычислительная система. Необходимо описать в теоретическом разделе все три уровня, показав связи между ними.
Объекты реальности
Как правило, мы ожидаем, что термины предметной области знакомы читателю технической документации, в противном случае ему следовало бы обратиться сначала к учебнику. Тем не менее, ограничиваться простым перечислением рассматриваемых объектов было бы опрометчиво по следующим причинам:
- значения терминов могут быть размытыми или обусловленными контекстом их употребления;
- термины бывают многозначными, особенно в развитых предметных областях с богатой историей;
- значение термина в конкретном документе может быть шире или конкретнее общепринятого.
Такие термины нуждаются в уточнении. Вместе с тем, автор документа вынужден выбирать, какие термины следует ввести явно, а какие можно считать заведомо понятными читателю. Например, он может прийти к выводу, что термин контрагент приобретает в документе специфическое значение, а термины дебиторская задолженность и кредиторская задолженность остаются стандартными для бухгалтерского учета и не требуют уточнений.
Объекты модели
Объект модели «остается» от объекта реальности после того, как мы абстрагировались от избыточных деталей или от обстоятельств, которые следовало бы, но не получается принять во внимание по техническим причинам. Описывая объекты модели, следует указать на те качества и параметры реального объекта, которые учитывает система, а также раскрыть взаимосвязи между их значениями. Например, состояние некоторого объема идеального газа определяется его температурой, объемом и установившемся в нем давлением. Зависимости между значениями этих параметров описывает закон Бойля-Мариотта. Реальный газ ведет себя сложнее, однако, для решения многих задач вполне достаточно такого упрощения.
Необходимость в отдельных терминах для обозначения объектов модели возникает не всегда. Авторы документа могут использовать один и тот же термин для реального объекта и его модели или для его модели и представления в системе. Чрезмерная наукообразность вредит тексту не меньше поверхностности.
Объекты системы
Термины, указывающие на виртуальные образы реальных объектов, позволяют последовательно отличать объекты предметной области от их цифровых двойников. Клиент — это живой человек, а учетная запись — его образ в системе. Дело не только в том, что разговоры о ликвидации клиента звучат зловеще, а ликвидация учетной записи — рабочий момент. К подобным условностям легко привыкаешь, не слышим же мы ничего живодерского в щелканье мышью. Важнее, что нам предстоит объяснить читателю, как именно клиент становится пользователем. Назвав учетную запись клиента в системе словом клиент, мы вынудим себя рассказывать о создании клиента для клиента, что может запутать аудиторию и создать комический эффект.
Пример
Обсудим следующий пример, это фрагмент теоретического раздела технического документа, описывающего вымышленную автоматизированную систему проведения взаимозачетов.
① | Участником экономической деятельности будем называть физическое или юридическое лицо, совершающее хозяйственные операции и вступающее в сделки с другими лицами на законных основаниях. Реквизитами участника экономической деятельности называются данные, которые позволяют однозначно его идентифицировать. Зачетом будем называть хозяйственную операцию, в результате которой участник экономической деятельности сокращает свою дебиторскую и кредиторскую задолженность на одну и ту же ненулевую сумму, не отчуждая своих активов в пользу других участников экономической деятельности и не принимая отчуждаемых ими активов, а также не оказывая им никаких услуг и не получая от них никаких услуг. Поскольку участник экономической деятельности не вправе обосновать зачет одним лишь собственным решением, будем говорить, что он получает его на основании той или иной сделки с другими участниками. Взаимозачетом будем называть сделку между несколькими участниками экономической деятельности, в результате которой каждый из них получает зачет. |
② | Контрагентом будем называть участника экономической деятельности, который использует систему для проведения взаимозачетов с другими участниками экономической деятельности. В состав реквизитов контрагента входят следующие данные:
Балансом контрагента здесь будем называть размер его дебиторской или кредиторской задолженности во взаиморасчетах с оператором системы. При наличии дебиторской задолженности баланс считается положительным, а при наличии кредиторской — отрицательным. |
③ | Каждый контрагент представлен в системе своей учетной записью. К учетной записи контрагента привязаны следующие информационные ресурсы:
Карточка контрагента содержит его реквизиты, а также дополнительные справочные данные, указанные им самим. Другие пользователи системы имеют возможность просматривать карточки контрагентов. На виртуальном счете контрагента находятся денежные средства, номинированные во внутренней валюте системы. Остаток денежных средств на виртуальном счете контрагента равен его балансу. Портфель задолженностей контрагента содержит данные о дебиторской и кредиторской задолженности, которую этот контрагент предлагает для проведения взаимозачетов с другими контрагентами. |
Приведенный выше фрагмент структурирован следующим образом.
① Перечисление явлений предметной области, с которыми имеет дело система.
Если читатель документа намерен воспользоваться системой для проведения взаимозачетов или заняться ее разработкой, то наверно он в курсе, кто обычно участвует в экономической деятельности, и что такое взаимозачет. С другой стороны, его знания могут оказаться чересчур обширными или, наоборот, однобокими. Поэтому авторы объясняют ему, в каких границах и формах они здесь рассматривают эти явления. Например, они находят нужным подчеркнуть, что взаимозачет может быть многосторонним, но не может быть барной сделкой.
② Информационная модель рассматриваемых объектов предметной области.
Авторы показывают, что «остается» от явления предметной области после того, как мы абстрагировались от деталей, не имеющих значения для системы. Например, нам важны реквизиты предприятия, но безразличны его кадровый состав и ассортимент выпускаемой продукции. С другой стороны, объекты предметной области способны приобретать дополнительные свойства по отношению к системе. Так, участник экономической деятельности получает в ней роль контрагента, и появляется возможность говорить о балансе его взаиморасчетов с ней.
③ Средства представления объектов предметной области в системе.
В этой части объектам предметной области сопоставлены их отражения в системе: контрагент представлен своей учетной записью, его реквизиты — карточкой, баланс — виртуальным счетом и т. п.
Структура показанного выше фрагмента вполне правдоподобна, но составлена именно таким образом в методических целях. Авторы документа могли бы последовательно рассматривать каждое явление предметной области, описывая в едином блоке сначала само это явление, затем его модель и, наконец, представление в системе. Кроме того, они могли бы включать описания моделей в описания явлений (есть контрагент, а у него такие-то свойства) или преставлений (есть карточка, а у нее вот такие поля). Однако при любом способе построения теоретического радела они решали бы одну и ту же задачу: сопоставление явлениям предметной области их моделей и воплощающих эти модели средств.
Процессы предметной области
Любая вычислительная система тем или иным способом преобразует входные данные в выходные. Как бы ни было велико разнообразие способов ввода, вывода и представления данных, суть происходящего остается неизменной. Потребителям и разработчикам системы недостаточно знания тех объектов, цифровыми представлениями которых эта система оперирует. Необходимо понимать, что происходит с ними в системе, из чего и каким образом она производит полезный результат. Такое понимание включает в себя знание основных процессов, выполняемых или моделируемых системой, а также условий, которые приводят к запуску этих процессов и делают их возможными. Важны не только события, происходящие в системе, но и причины, которыми они могут быть вызваны.
Система и работа с ней
Целевое применение любых средств возможно только в составе какой-то системы, точнее, вычислительной системы, если мы говорим о решениях в сфере информационных технологий. В теоретическом разделе документа следует перечислить основные сценарии работы с системой и дать каждому из них краткую характеристику. Необходимо также объяснить, каким образом эти сценарии связаны между собой, в частности, как выполнение одних сценариев обеспечивает возможность выполнения других или, наоборот, исключает его. Такое описание позволяет читателю понять, каким образом организована деятельность пользователей и персонала системы, и откуда берутся необходимые для ее функционирования ресурсы. Представив читателю общую картину деятельности, связанной с системой, можно описать каждый сценарий подробно в самостоятельном разделе.
Сценарии работы системы
Сценарии работы с системой можно разделить на следующие группы по их назначению:
- прикладные;
- эксплуатационные;
- эксплуатационно-прикладные.
Прикладные сценарии работы системы непосредственно непосредственно приводят к получению ожидаемых от нее полезных результатов. Содержание таких сценариев полностью определяется назначением системы и набором ее функций.
Эксплуатационные сценарии предусматривают работы, направленные на поддержание системы в работоспособном состоянии. Распространенные примеры таких сценариев — резервное копирование данных, восстановление данных из резервных копий, оптимизация БД, масштабирование системы или отдельных ее частей и т. п.
Эксплуатационно-прикладные сценарии направлены на обеспечение работоспособности системы, но обращаются к ее прикладной функциональности. К этой группе сценариев относится, например, предусмотренное во многих системах ведение справочников НСИ.
Сценарии можно разделить на следующие группы по стадиям жизненного цикла системы:
- сценарии стадии внедрения;
- сценарии стадии промышленной эксплуатации.
Сценарии стадии внедрения выполняют однократно при вводе системы в эксплуатацию. Таким сценарием может быть, например, создание административных учетных записей, импорт данных из систем предыдущего поколения, первоначальная загрузка НСИ, настройка всевозможных шаблонов, правил и т. п. Легко видеть, что эти сценарии относятся к группе эксплуатационных и эксплуатационно-прикладных. Конечно, персонал системы может выполнять их и на стадии промышленной эксплуатации системы. Однако стадия внедрения требует их выполнения в наибольшем объеме, поскольку этим создается «ландшафт» для дальнейшей работе в системе.
Сценарии стадии промышленной эксплуатации включают в себя текущую работу в системе и ее штатное обслуживание.
Лексический инструментарий автора
В теоретическом разделе автор создает себе лексический инструментарий для ясного и лаконичного изложения материала основной части документа. Кроме терминов, описывающих предметную область и порядок функционирования системы, к нему обычно относятся следующие группы слов:
- обобщающие термины;
- уточняющие термины;
- сопутствующая лексика.
Обобщающие термины
Обобщающие термины оберегают автора от необходимости многократно включать в текст устойчивые перечисления. Если какая-то система стереотипно работает с данными о поездах, автомобилях и повозках, то удобнее ввести для них термин наземный транспорт и пользоваться им, чем то и дело поминать все троицу. Велосипеды и квадроциклы останутся за раками этого понятия, однако, при необходимости несложно включить их туда, переписав определение.
Уточняющие термины
Уточняющие термины помогают исключить из текста навязчивые повторения устойчивых определений. Такими обычно бывают обороты со словом который, причастные обороты и цепочки существительных в родительном падеже. Они загромождают текст, мешают читателю, а добросовестного автора вынуждают бороться с неблагозвучными повторами.
Обломов остановился и прочитал написанное.
— Нескладно, — сказал он, — тут два раза сряду что, а там два раза который.
Он пошептал и переставил слова: вышло, что который относится к этажу — опять неловко. Кое-как переправил и начал думать, как бы избежать два раза что.
Он то зачеркнет, то опять поставит слово. Раза три переставлял что, но выходило или бессмыслица, или соседство с другим что.
— И не отвяжешься от этого другого-то что! — сказал он с нетерпением. — Э! да черт с ним совсем, с письмом-то! Ломать голову из таких пустяков! Я отвык деловые письма писать. А вот уж третий час в исходе.
, «Обломов».
Сопутствующая лексика
Сопутствующая лексика, которую еще можно назвать околотерминологической, в основном указывает на действия, совершаемые предметами, обозначенными с помощью терминов, или по отношению к ним. Какой глагол выбрать для действия, приводящего к появлению в системе новой учетной записи? Должны ли мы ее создать, добавить или завести, словно домашнего питомца? Спонтанное использование сопутствующей лексики делает ее многозначной и мешает правильному пониманию текста аудиторией. Мы рискуем запутать читателя, рассказав ему сначала о добавлении учетной записи в систему, а потом о ее добавлении в какую-то группу пользователей. Во избежание подобных конфликтов сопутствующая лексика должна быть тщательно продумана.
Пример
Представим себе сервис электронного документооборота, о которой в технической документации сказано следующее.
Задача этого предложения — сообщить читателю об одной из функций системы. Для ее решения автору хватило бы слов десяти, остальные ушли на попытки объяснить, кто вовлечен в ситуацию, и что получается в результате. Конечно, одна громоздкая фраза текст не погубит, но без аккуратно выстроенной терминологической системы он весь будет выдержан в подобном стиле. Перегрузив его перечислениями и определительными оборотами, мы вынудим читателя продираться через них в попытках разглядеть смысла.
Снабдим документ теоретическим разделом, включив в него следующие определения.
Основные понятия и определения
Лицом будем назвать физическое или юридическое лицо, обладающее правоспособностью в той юрисдикции, где применяется система.
Участником электронного документооборота (или просто участником) будем называть лицо, имеющее учетную запись в системе.
Полноправным будем называть участника, относящегося к одной из следующих категорий:
- физическое лицо, прошедшее процедуру идентификации;
- юридическое лицо, загрузившее в систему квалифицированную электронную подпись руководителя.
Юридически значимым будем называть документ, подписание которого сторонами создает или изменяет их взаимные обязательства.
Теперь перепишем исходное предложение, используя подготовленную терминологию.
Восемь слов вместо пятидесяти двух! Трудиться над теоретическим разделом, чтобы сократить единственную фразу, не было бы смысла, но если речь идет о тексте значительного объема, в котором эти понятия фигурирую постоянно, он оправдает себя многократно и по авторским, и по читательским усилиям. Не забудем и о том, что границы используемых в документе понятий могут меняться. Например, по мере развития системы к участию в электронном документообороте могут допустить обособленные подразделения организаций без образования юридического лица или неформальные объединения граждан. В этом случае достаточно будет переписать определения, избежав внесения массовой чреватой ошибками правки по всему тексту.