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

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

Создан 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 перечисления.

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

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

• ГОСТ 2.105–95 Единая система конструкторской документации. Общие требования к текстовым документам;
• ГОСТ 19.106–78 Единая система программной документации. Требования к программным документам, выполненным печатным способом;
• ГОСТ 28806–90 Качество программных средств. Термины и определения;
• ГОСТ 8.417–2002 Государственная система обеспечения единства измерений. Единицы физических величин и ряда других нормативных документов,
• а оценить ее качество, включая понятность, с помощью ГОСТ 28195–89 Оценка качества программных средств. Общие положения.

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