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

Принципы оформления (формула ТУПО):

  • Точность.
  • Удобочитаемость.
  • Последовательность.
  • Ориентация на конкретную аудиторию.

Теперь рассмотрим каждый из пунктов подробнее.

Точность

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

Хотя бывают комические ситуции. Случай из практики.

После окончания работы над одним из документов он был передан руководителю проекта. Полистав и покрутив в руках готовый документ, руководитель выдал следующее: “Я понимаю, что здесь всё только самое важное и вы подошли с полным понимаем к его подготовке, погрузившись во все детали. Но боюсь, что заказчик, не совсем корректно сопоставит затраты на документ и его объём. В общем, добавьте ещё страниц…”. Обоснование объёма подготовленного документа не растопило сердце проектного менеджера. Пришлось “дорабатывать”. И тут душа понеслась в рай… Через несколько дней “доработанный” документ был предоставлен руководителю повторно и… Чудо случилось. “Ну, вот! Другое дело. Нарядно и страниц много. Спасибо!”

Думаю, всё здесь понятно.

Техническая документация - это “точное” произведение. Но в жизни всякое случается…

Удобочитаемость

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

При этом удобочитаемость бывает двух видов:

  • полиграфическая,
  • лингвистическая.

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

  • шрифты и их размеры,
  • цвет и контрастность текста,
  • выравнивание текста,
  • длина строки,
  • ширина полей страницы и т.д.

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

Последовательность

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

Ориентация на конкретную аудиторию

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

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