Перейти на главную страничку сайта (список статей, файлы для скачивания)

ФОРУМ (здесь можно обсудить эту статью, а также любые проблемы программирования на различных макроязыках и в скриптовых средах)

Принципы разработки документации к программному обеспечению

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

В состав технической документации как правило входят две основные части:

Эти части могут существовать и в интегрированном виде.

Существует несколько сценариев использования документации пользователем:

Пользователь вправе рассчитывать, что следуя любому из этих сценариев, он быстро сможет отыскать нужную ему информацию.

Общая логика изложения в документации сводится к следующему:

Недопустимо ставить цель и не указывать способ её достижения. Недопустимо описывать способ достижения цели, не сформулировав самой цели. Недопустимо смешивать внешние и внутренние объекты (например, документ как таковой и файл документа).

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

Размещение информации может выглядеть примерно так:

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


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

Основные виды заголовков:

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


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

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

В то же время дублирование информации может затруднять поиск нужных тем, а также создание индекса, системы ссылок и т.п.

Несколько рекомендаций:


Текст документации состоит из основного текста, на фоне которого обособляются выделенные сведения.

К выделенным сообщениям относятся:

К выделенным элементам относятся:

Удобно, когда тема сначала конспективно разбита на основные "опорные точки", пункты, а затем изложена подробно - поочерёдно по каждому из пунктов. Это удобно и для запоминания, и для систематического усвоения. Пункты перечисления даются в виде списка с символами бюллетеня (жирными точками).


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

Предметно-понятийная лексика включает в себя несколько основных групп:

Далее - несколько рекомендаций по лексике действий и отношений.

Не рекомендуется злоупотреблять сослагательным наклонением. Например, не рекомендуется писать: "Если бы вы хотели сохранить файл...", лучше писать: "Если вы хотите сохранить файл...".

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

Иногда родственные глаголы образуют целые "гнёзда", внутри которых различаются по способу действия. Например, "писать", "написать", "дописать", "переписать". Следует стараться использовать правильное слово в каждой ситуации.

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

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

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

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


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

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

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

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

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

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

Техническая документация допускает более частое, чем обычный литературный текст, повторение отдельных слов и выражений. Рекомендуется, допуская такие повторы, подчёркивать каждый раз, что повтор является намеренным. Например, вместо: "Вы можете изменять значения параметров настройки. Значения параметров настройки содержатся в файле настройки" можно написать: "Вы можете изменять значения параметров настройки. Эти значения содержатся в особом файле, который называется файлом настройки".

Усложнённый синтаксис делает документацию труднодоступной. Необходимо бороться с конструкциями, которые не являются оптимальными для восприятия:


В статье использованы материалы данного руководства.

Людоговский Александр

Перейти на главную страничку сайта (список статей, файлы для скачивания)

© 2007 http://www.script-coding.com При любом использовании материалов сайта обязательна ссылка на него как на источник информации, а также сохранение целостности и авторства материалов.