Ни в форумах, ни в блогах, ни в России, ни в англоязычных ресурсах я не смог найти информацию о том, как логично упаковать всю релевантную фактуру в приятный технический документ. В книге М. Ильяхова «Пиши, сокращай» есть отдельная глава про дидактику, но там очень мало, вскользь и не совсем о том.
Еще есть ГОСТы 34 и 19 — там уже написано, из каких разделов должен состоять стандартизованный документ, но ведь кроме стандартизованных есть и другие документы — во всяком случае заказы на таковые ко мне приходили, — и каждый раз приходилось ломать голову.
![Рис 1. Выдержка из ГОСТ 19.105-78 (п. 1.2) — требования к структуре руководства системного администратора Рис 1. Выдержка из ГОСТ 19.105-78 (п. 1.2) — требования к структуре руководства системного администратора](https://habrastorage.org/getpro/habr/upload_files/b57/96d/261/b5796d261044e527c0f9a6e8275a92a5.png)
Наиболее творческим документом в этом плане, по моему весьма скромному техписовскому опыту, был whitepaper — в каждом заказе получалась разная структура.
![Рис. 2. Два оглавления из разных whitepaper'ов — структуры совершенно разные Рис. 2. Два оглавления из разных whitepaper'ов — структуры совершенно разные](https://habrastorage.org/getpro/habr/upload_files/5c3/f91/bde/5c3f91bde399b5dbf8c5b3f6da862140.png)
Причина игнора этой темы мне совершенно непонятна, так как, например, у меня 90% техписовской работы — это анализ собранной инфы и раскладывание ее по полкам (не думаю, что я в этом плане какой‑то особенный). Соответственно, мне было бы удобно, чтобы кто‑то научил, какими методами это можно делать.
Дело в том, что правильная (=логичная и сбалансированная) структура документа не только упрощает усвоение документа целевым читателем, но и ускоряет работу писателя. Во‑первых, исключаются всякие дублирования. Во‑вторых, когда ты знаешь, из каких глав, разделов и подразделов состоит твой документ и в каком порядке их надо расположить, ты чаще задаешь себе (и заказчику) правильные вопросы. Соответственно, ты быстрее понимаешь, нужен ли в документе найденный тобой факт/фича/характеристика/требование и, если нужен, то в какую часть документа надо положить находку.
Отмечу также, что наука о структуре работ у других типов писателей, — нетехписов (!), — подходит лишь ограниченно. Например, про структуру статьи много пишется у копирайтеров (например, см. классическую формулу AIDA — Attention, Interest, Desire, Action — внимание, интерес, желание, действие), но копирайтерские подходы тут не работают — мы ведь не продаем продукт, а инструктируем или обучаем читателя.
Также много про структуру произведения пишут и беллетристы (например, М. Веллер «Технология рассказа»), но и там мимо, ибо с самого начала нужна интрига — а в техдоке какая интрига?
В итоге мне‑таки удалось найти разрозненные сведения по этому вопросу из одного англоязычного учебника для техписов (Handbook of Technical Writing, G. J. Alred), и я решил их собрать в кучку и поделиться с теми, кого этот вопрос тоже интересовал (привожу с сокращениями, более развернутая версия в учебнике — можете его нагуглить или напишите в личку, поделюсь).
В книге авторы предлагают 8 принципов изложения/расположения технической информации.
1. Причина и следствие
Описание начинается с причины или со следствия определенного события. Этот принцип используется в документах, которые предлагают решить техническую проблему. Такой документ может либо начинаться с описания проблемы и заканчиваться ее решением, либо наоборот — начинаться с решения, заканчиваться описанием. Описывая причину (проблему) со множеством последствий иногда целесообразно объединять этот принцип с принципом изложения «по важности» (п. 5).
2. Хронология
При использовании хронологического принципа изложение строится вокруг моментов времени, изложенных в хронологическом порядке. Такой принцип используется в отчетах о командировке, отчетах о ходе работ, инструкциях, расписаниях; реже в протоколах собраний и отчетах об инцидентах. Также это классический способ излагать факты в объяснительных записках и т.п. повествованиях.
![Рис. 3. Пример из отчета об инциденте. Рис. 3. Пример из отчета об инциденте.](https://habrastorage.org/getpro/habr/upload_files/bdc/0c7/af1/bdc0c7af132b9989bf98a9a0240eb587.png)
Я также сталкивался с такой подачей материала в программном документе «Программа и методика испытаний» (очень похоже на пошаговое описание (см. п. 6 ниже), но учитывая синхронизацию по времени между действием и ожидаемым результатом, я отнес пример сюда, см. рис. 4)
![Рис. 4. Пример синхронизированного по времени описания в ПМИ. Рис. 4. Пример синхронизированного по времени описания в ПМИ.](https://habrastorage.org/getpro/habr/upload_files/c42/c88/dc1/c42c88dc198f57b149354d0796b8b34c.png)
3. Сравнение
Принцип сравнения полезен в ситуациях, когда новая тема по многим параметрам схожа с более известной для читателя темой. Суть метода заключается в выявлении общих и уникальных характеристик для нескольких объектов.
Сначала выявляется основа (набор характеристик) для сравнения (см. рис. 5).
![Рис. 5. Пример набора характеристик для проведения сравнения Рис. 5. Пример набора характеристик для проведения сравнения](https://habrastorage.org/getpro/habr/upload_files/9d4/e41/974/9d4e419746de40337f52cc26b14404bb.png)
Затем выбирается способ их представления (см. рис. 6), например:
сначала приводятся все характеристики одного объекта, потом следующего; или
сначала приводится одна характеристика всех объектов, потом следующая.
![Рис. 6. Пример сопоставления характеристик одного из продуктов. Рис. 6. Пример сопоставления характеристик одного из продуктов.](https://habrastorage.org/getpro/habr/upload_files/335/d47/409/335d474093e86464243f9161d46d4f33.png)
При использовании этого принципа удобно использовать таблицы.
4. Дробление и систематизация
При использовании принципа дробления и систематизации техпис:
дробит целое на части и затем описывает каждую часть по отдельности,
раскладывает части по интуитивно понятным категориям, т. е. систематизирует.
![Рис. 7. Пример систематизированных параметров — типов данных в Python Рис. 7. Пример систематизированных параметров — типов данных в Python](https://habrastorage.org/getpro/habr/upload_files/5cf/89c/e07/5cf89ce071a217d3665270b33b462efb.jpg)
5. По важности
Следуя этому принципу, технический писатель излагает пункты по убыванию или по возрастанию важности.
Убывание важности используется в проектных предложениях, где изложение начинается с самого важного пункта. Используется в докладных записках, письмах руководителям, аналитических отчетах.
Возрастание важности используется в технических презентациях, где изложение заканчивается самым важным пунктом.
![Рис. 8. Пример перечисления характеристик по убыванию важности для конечного клиента (судил по себе) Рис. 8. Пример перечисления характеристик по убыванию важности для конечного клиента (судил по себе)](https://habrastorage.org/getpro/habr/upload_files/e84/23a/3f3/e8423a3f3d5b94ba60fa8f4820f30836.png)
6. По шагам
В основе пошагового принципа описания лежит описание элементов в том порядке, в котором они задействованы в процессе. Чаще всего этот принцип используется в пошаговых инструкциях. Основной недостаток этой логики изложения — отсутствие акцентов на определенных важных нюансах. В том или ином виде этот принцип применяется в других принципах (хронология, причина и следствие и т. д.)
![Рис. 9. Пример пошагового описания действий. Рис. 9. Пример пошагового описания действий.](https://habrastorage.org/getpro/habr/upload_files/389/4d1/cb9/3894d1cb9b6f53118fd362bf0db4f5d3.png)
7. По расположению
Этот принцип используется при описании внешнего вида физического объекта и продвигается от верхних элементов к нижним, от внутренних к внешним, от расположенных впереди к расположенным сзади и т. д.
При этом типе изложения часто приводятся чертежи, рисунки, иллюстрации, схемы.
![Рис. 10. Пример описания схемы сети по расположению ее элементов. Рис. 10. Пример описания схемы сети по расположению ее элементов.](https://habrastorage.org/getpro/habr/upload_files/381/d6f/8e4/381d6f8e4850646c503a85ae0d1b2534.png)
8. От общего к частному и наоборот
Используя этот принцип, техпис двигается либо от общих наблюдений в сторону частных случаев, либо наоборот. Этот принцип популярен в обучающих материалах, когда читателю нужно дать общеизвестную информацию, а потом постепенно погружать его в подробности.
![Рис. 11. Пример описания от общих положений (п. 2) к частным деталям (п. 8). Рис. 11. Пример описания от общих положений (п. 2) к частным деталям (п. 8).](https://habrastorage.org/getpro/habr/upload_files/6f1/3bc/3d5/6f13bc3d518c6d4d967793024a1f1763.png)
Отмечу, что в учебнике есть и 9-й принцип — принцип определений, но я решил его не включать сюда, т.к. он относится к описанию единичных концепций, а мне нужно было понять, как подавать факты группой, оптом, в легкоусвояемом виде.
В учебнике также говорится, что техпису обычно приходится комбинировать эти принципы — например, разделы идут по логике одного принципа, а внутри разделов изложение может строиться на другом принципе.
Со своей стороны могу подтвердить верность этого наблюдения. В частности, я недавно делал тестовое задание на 500 слов про направления в дизайнах мобильных приложений, и там для общей схемы документа потребовалось применить ко всему документу систематизацию (принцип № 4) направлений, а в подразделах — ранжирование характеристик направления по их важности для заказчика (принцип № 5).
Как‑то так. Надеюсь, эта инфа оказалась полезной не только мне. Если что, извините за потраченное время:).