Что такое техническая документация? Часть II - понимаемое понятное понятие «понятности техдокументации»

Часто приходится слышать от заказчиков: «Нам надо не по ГОСТам, хотим, чтобы техдокументация была понятной». В первом приближении звучит как «Да, да! Сделайте нам красиво! В Большом театре нам постоянно делают красиво...». Но у нас не Большой с его вечными дрязгами: прагматики мы, а не креаклы, и творческая деятельность не по нашей кафедре. Покажем на практике, что понятная техдокументация разрабатывается только по ГОСТам, ведь само понятие понятности ГОСТировано. Редакция от 14.11.2021.

Создан 20.01.2015 11:22:48

- Маяковский "Баня"

Итак, что же такое понятность в общеупотребительном смысле?

Понятность - разборчивость, ясность, вразумительность, отчетливость, внятность, доходчивость, доступность, общепонятность, удобопонятность, общедоступность, справедливость, толковость, удобоваримость, популярность, прозрачность, объяснимость, очевидность… Словарь синонимов.

Общеупотребительное понятие прекрасно коррелирует с подхарактеристиками удобства использования по ГОСТ 28806-90, в частности, с понимаемостью и осваиваемостью программного средства. Напомним, что программное средство есть «Программа, предназначенная для многократного применения на различных объектах, разработанная любым способом и снабженная комплектом программных документов [из 13 табл. 3 ГОСТ 28195-89]», поэтому понимаемость и осваиваемость программного средства в огромной степени определяются понятностью и понимаемостью программных документов, т.е. техдокументацией.

Понимаемость и осваиваемость являются оценочными элементами фактора «удобство применения» по ГОСТ 28195-89.

Далее:
Полнота технической документации как показатель ее понятности
Точность пользовательской документации как показатель ее понятности
Техническое исполнение пользовательской документации как показатель ее понятности
И, наконец, собственно понятность пользовательской документации
Мораль (выводы)

Полнота технической документации как показатель ее понятности

- Полнота технической документации

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

  1. Наличие краткой аннотации;
  2. Наличие описания решаемых задач;
  3. Наличие описания структуры функций ПС;
  4. Наличие описания основных функций ПС;
  5. Наличие описания частных функций;
  6. Наличие описания алгоритмов;
  7. Наличие описания межмодульных интерфейсов;
  8. Наличие описания пользовательских интерфейсов;
  9. Наличие описания входных и выходных данных;
  10. Наличие описания диагностических сообщений;
  11. Наличие описания основных характеристик ПС;
  12. Наличие описания программной среды функционирования ПС;
  13. Достаточность документации для ввода ПС в эксплуатацию;
  14. Наличие информации технологии переноса для мобильных программ.

Все надо для понимаемости? Практически все, почти ничего лишнего.

Точность пользовательской документации как показатель ее понятности

Теперь о точности пользовательской документации (оценочные элементы):

  1. Соответствие оглавления содержанию документации;
  2. Оценка оформления документации;
  3. Грамматическая правильность изложения документации;
  4. Отсутствие противоречий;
  5. Отсутствие неправильных ссылок;
  6. Ясность формулировок и описаний;
  7. Отсутствие неоднозначных формулировок и описаний;
  8. Правильность использования терминов;
  9. Краткость, отсутствие лишней детализации;
  10. Единство формулировок;
  11. Единство обозначений;
  12. Отсутствие ненужных повторений;
  13. Наличие нужных объяснений.

Все надо для понимаемости? Однозначно - точность техдокументации не даст возможности завести пользователя в тупик, вызвать у него умственное пресыщение 😂

Техническое исполнение пользовательской документации как показатель ее понятности

Техническое исполнение пользовательской документации (оценочные элементы):

  1. Наличие оглавления;
  2. Наличие предметного указателя;
  3. Наличие перекрестных ссылок;
  4. Наличие всех требуемых разделов;
  5. Соблюдение непрерывности нумерации страниц документов;
  6. Отсутствие незаконченных разделов абзацев, предложений;
  7. Наличие всех рисунков, чертежей, формул, таблиц;
  8. Наличие всех строк и примечаний;
  9. Логический порядок частей внутри главы.

Все надо для понимаемости? См. выше.

И, наконец, собственно понятность пользовательской документации

Понятность пользовательской документации (оценочные элементы):

  1. Оценка стиля изложения;
  2. Дидактическая разделенность;
  3. Формальная разделенность;
  4. Ясность логической структуры;
  5. Соблюдение стандартов и правил изложения в документации;
  6. Оценка по числу ссылок вперед в тексте документов.

А вот здесь подробнее. Стиль изложения уж точно не должен быть водевильным, см. Как писать техническую документацию? Про п. 2 умолчим, п. 5 по смыслу включает в себя пп. 3 и 4 перечисления.

Мораль (выводы)

Как ни крути, а понятную техническую документацию возможно разработать исключительно по ГОСТам, в частности, с применением:

Так что не стоит кочевряжиться: разрабатываем понятную документацию по ГОСТам, а затем - айда в баню с нами! - Смайл дринк