Как техпису изложить фактуру в техдоке?
Ни в форумах, ни в блогах, ни в России, ни в англоязычных ресурсах я не смог найти информацию о том, как логично упаковать всю релевантную фактуру в приятный технический документ. В книге М. Ильяхова «Пиши, сокращай» есть отдельная глава про дидактику, но там очень мало, вскользь и не совсем о том.
Еще есть ГОСТы 34 и 19 — там уже написано, из каких разделов должен состоять стандартизованный документ, но ведь кроме стандартизованных есть и другие документы — во всяком случае заказы на таковые ко мне приходили, — и каждый раз приходилось ломать голову.
Наиболее творческим документом в этом плане, по моему весьма скромному техписовскому опыту, был whitepaper — в каждом заказе получалась разная структура.
Причина игнора этой темы мне совершенно непонятна, так как, например, у меня 90% техписовской работы — это анализ собранной инфы и раскладывание ее по полкам (не думаю, что я в этом плане какой‑то особенный). Соответственно, мне было бы удобно, чтобы кто‑то научил, какими методами это можно делать.
Дело в том, что правильная (=логичная и сбалансированная) структура документа не только упрощает усвоение документа целевым читателем, но и ускоряет работу писателя. Во‑первых, исключаются всякие дублирования. Во‑вторых, когда ты знаешь, из каких глав, разделов и подразделов состоит твой документ и в каком порядке их надо расположить, ты чаще задаешь себе (и заказчику) правильные вопросы. Соответственно, ты быстрее понимаешь, нужен ли в документе найденный тобой факт/фича/характеристика/требование и, если нужен, то в какую часть документа надо положить находку.
Отмечу также, что наука о структуре работ у других типов писателей, — нетехписов (!), — подходит лишь ограниченно. Например, про структуру статьи много пишется у копирайтеров (например, см. классическую формулу AIDA — Attention, Interest, Desire, Action — внимание, интерес, желание, действие), но копирайтерские подходы тут не работают — мы ведь не продаем продукт, а инструктируем или обучаем читателя.
Также много про структуру произведения пишут и беллетристы (например, М. Веллер «Технология рассказа»), но и там мимо, ибо с самого начала нужна интрига — а в техдоке какая интрига?
В итоге мне‑таки удалось найти разрозненные сведения по этому вопросу из одного англоязычного учебника для техписов (Handbook of Technical Writing, G. J. Alred), и я решил их собрать в кучку и поделиться с теми, кого этот вопрос тоже интересовал (привожу с сокращениями, более развернутая версия в учебнике — можете его нагуглить или напишите в личку, поделюсь).
В книге авторы предлагают 8 принципов изложения/расположения технической информации.
1. Причина и следствие
Описание начинается с причины или со следствия определенного события. Этот принцип используется в документах, которые предлагают решить техническую проблему. Такой документ может либо начинаться с описания проблемы и заканчиваться ее решением, либо наоборот — начинаться с решения, заканчиваться описанием. Описывая причину (проблему) со множеством последствий иногда целесообразно объединять этот принцип с принципом изложения «по важности» (п. 5).
2. Хронология
При использовании хронологического принципа изложение строится вокруг моментов времени, изложенных в хронологическом порядке. Такой принцип используется в отчетах о командировке, отчетах о ходе работ, инструкциях, расписаниях; реже в протоколах собраний и отчетах об инцидентах. Также это классический способ излагать факты в объяснительных записках и т.п. повествованиях.
Я также сталкивался с такой подачей материала в программном документе «Программа и методика испытаний» (очень похоже на пошаговое описание (см. п. 6 ниже), но учитывая синхронизацию по времени между действием и ожидаемым результатом, я отнес пример сюда, см. рис. 4)
3. Сравнение
Принцип сравнения полезен в ситуациях, когда новая тема по многим параметрам схожа с более известной для читателя темой. Суть метода заключается в выявлении общих и уникальных характеристик для нескольких объектов.
Сначала выявляется основа (набор характеристик) для сравнения (см. рис. 5).
Затем выбирается способ их представления (см. рис. 6), например:
сначала приводятся все характеристики одного объекта, потом следующего; или
сначала приводится одна характеристика всех объектов, потом следующая.
При использовании этого принципа удобно использовать таблицы.
4. Дробление и систематизация
При использовании принципа дробления и систематизации техпис:
дробит целое на части и затем описывает каждую часть по отдельности,
раскладывает части по интуитивно понятным категориям, т. е. систематизирует.
5. По важности
Следуя этому принципу, технический писатель излагает пункты по убыванию или по возрастанию важности.
Убывание важности используется в проектных предложениях, где изложение начинается с самого важного пункта. Используется в докладных записках, письмах руководителям, аналитических отчетах.
Возрастание важности используется в технических презентациях, где изложение заканчивается самым важным пунктом.
6. По шагам
В основе пошагового принципа описания лежит описание элементов в том порядке, в котором они задействованы в процессе. Чаще всего этот принцип используется в пошаговых инструкциях. Основной недостаток этой логики изложения — отсутствие акцентов на определенных важных нюансах. В том или ином виде этот принцип применяется в других принципах (хронология, причина и следствие и т. д.)
7. По расположению
Этот принцип используется при описании внешнего вида физического объекта и продвигается от верхних элементов к нижним, от внутренних к внешним, от расположенных впереди к расположенным сзади и т. д.
При этом типе изложения часто приводятся чертежи, рисунки, иллюстрации, схемы.
8. От общего к частному и наоборот
Используя этот принцип, техпис двигается либо от общих наблюдений в сторону частных случаев, либо наоборот. Этот принцип популярен в обучающих материалах, когда читателю нужно дать общеизвестную информацию, а потом постепенно погружать его в подробности.
Отмечу, что в учебнике есть и 9-й принцип — принцип определений, но я решил его не включать сюда, т.к. он относится к описанию единичных концепций, а мне нужно было понять, как подавать факты группой, оптом, в легкоусвояемом виде.
В учебнике также говорится, что техпису обычно приходится комбинировать эти принципы — например, разделы идут по логике одного принципа, а внутри разделов изложение может строиться на другом принципе.
Со своей стороны могу подтвердить верность этого наблюдения. В частности, я недавно делал тестовое задание на 500 слов про направления в дизайнах мобильных приложений, и там для общей схемы документа потребовалось применить ко всему документу систематизацию (принцип № 4) направлений, а в подразделах — ранжирование характеристик направления по их важности для заказчика (принцип № 5).
Как‑то так. Надеюсь, эта инфа оказалась полезной не только мне. Если что, извините за потраченное время:).