Как техпису изложить фактуру в техдоке?

Ни в форумах, ни в блогах, ни в России, ни в англоязычных ресурсах я не смог найти информацию о том, как логично упаковать всю релевантную фактуру в приятный технический документ. В книге М. Ильяхова «Пиши, сокращай» есть отдельная глава про дидактику, но там очень мало, вскользь и не совсем о том.

Еще есть ГОСТы 34 и 19 — там уже написано, из каких разделов должен состоять стандартизованный документ, но ведь кроме стандартизованных есть и другие документы — во всяком случае заказы на таковые ко мне приходили, — и каждый раз приходилось ломать голову.

*Рис 1. Выдержка из ГОСТ 19.105-78 (п. 1.2) — требования к структуре руководства системного администратора*

рНаиболее творческим документом в этом плане, по моему весьма скромному техписовскому опыту, был whitepaper — в каждом заказе получалась разная структура.

Рис. 2. Два оглавления из разных whitepaper'ов — структуры совершенно разные — *Рис. 2. Два оглавления из разных whitepaper’ов — структуры совершенно разные*

Причина игнора этой темы мне совершенно непонятна, так как, например, у меня 90% техписовской работы — это анализ собранной инфы и раскладывание ее по полкам (не думаю, что я в этом плане какой-то особенный). Соответственно, мне было бы удобно, чтобы кто-то научил, какими методами это можно делать.

Дело в том, что правильная (=логичная и сбалансированная) структура документа не только упрощает усвоение документа целевым читателем, но и ускоряет работу писателя. Во-первых, исключаются всякие дублирования. Во-вторых, когда ты знаешь, из каких глав, разделов и подразделов состоит твой документ и в каком порядке их надо расположить, ты чаще задаешь себе (и заказчику) правильные вопросы. Соответственно, ты быстрее понимаешь, нужен ли в документе найденный тобой факт/фича/характеристика/требование и, если нужен, то в какую часть документа надо положить находку.

Отмечу также, что наука о структуре работ у других типов писателей, — нетехписов (!), — подходит лишь ограниченно. Например, про структуру статьи много пишется у копирайтеров (например, см. классическую формулу AIDA — Attention, Interest, Desire, Action — внимание, интерес, желание, действие), но копирайтерские подходы тут не работают — мы ведь не продаем продукт, а инструктируем или обучаем читателя.

Также много про структуру произведения пишут и беллетристы (например, М. Веллер «Технология рассказа»), но и там мимо, ибо с самого начала нужна интрига — а в техдоке какая интрига?

В итоге мне-таки удалось найти разрозненные сведения по этому вопросу из одного англоязычного учебника для техписов (Handbook of Technical Writing, G. J. Alred), и я решил их собрать в кучку и поделиться с теми, кого этот вопрос тоже интересовал (привожу с сокращениями, более развернутая версия в учебнике — можете его нагуглить или напишите в личку, поделюсь).

В книге авторы предлагают 8 принципов изложения/расположения технической информации:

1. Причина и следствие

Описание начинается с причины или со следствия определенного события. Этот принцип используется в документах, которые предлагают решить техническую проблему.Такой документ может либо начинаться с описания проблемы и заканчиваться ее решением, либо наоборот — начинаться с решения, заканчиваться описанием. Описывая причину (проблему) со множеством последствий иногда целесообразно объединять этот принцип с принципом изложения «по важности» (п. 5).

2. Хронология

При использовании хронологического принципа изложение строится вокруг моментов времени, изложенных в хронологическом порядке. Такой принцип используется в отчетах о командировке, отчетах о ходе работ, инструкциях, расписаниях; реже в протоколах собраний и отчетах об инцидентах. Также это классический способ излагать факты в объяснительных записках и т.п. повествованиях.

*Рис. 3. Пример из отчета об инциденте.*

Я также сталкивался с такой подачей материала в программном документе «Программа и методика испытаний» (очень похоже на пошаговое описание (см. п. 6 ниже), но учитывая синхронизацию по времени между действием и ожидаемым результатом, я отнес пример сюда, см. рис. 4)

*Рис. 4. Пример синхронизированного по времени описания в ПМИ.*

3. Сравнение

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

Сначала выявляется основа (набор характеристик) для сравнения (см. рис. 5).

*Рис. 5. Пример набора характеристик для проведения сравнения*

Затем выбирается способ их представления (см. рис. 6), например:

сначала приводятся все характеристики одного объекта, потом следующего; или
сначала приводится одна характеристика всех объектов, потом следующая.

*Рис. 6. Пример сопоставления характеристик одного из продуктов.*

При использовании этого принципа удобно использовать таблицы.

4. Дробление и систематизация

При использовании принципа дробления и систематизации техпис:

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

*Рис. 7. Пример систематизированных параметров — типов данных в Python*

5. По важности

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

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

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

*Рис. 8. Пример перечисления характеристик по убыванию важности для конечного клиента (судил по себе)*

6. По шагам

В основе пошагового принципа описания лежит описание элементов в том порядке, в котором они задействованы в процессе. Чаще всего этот принцип используется в пошаговых инструкциях. Основной недостаток этой логики изложения — отсутствие акцентов на определенных важных нюансах. В том или ином виде этот принцип применяется в других принципах (хронология, причина и следствие и т. д.)

*Рис. 9. Пример пошагового описания действий.*

7. По расположению

Этот принцип используется при описании внешнего вида физического объекта и продвигается от верхних элементов к нижним, от внутренних к внешним, от расположенных впереди к расположенным сзади и т. д.

При этом типе изложения часто приводятся чертежи, рисунки, иллюстрации, схемы.

*Рис. 10. Пример описания схемы сети по расположению ее элементов.*

8. От общего к частному и наоборот

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

*Рис. 11. Пример описания от общих положений (п. 2) к частным деталям (п. 8).*

Отмечу, что в учебнике есть и 9-й принцип — принцип определений, но я решил его не включать сюда, т.к. он относится к описанию единичных концепций, а мне нужно было понять, как подавать факты группой, оптом, в легкоусвояемом виде.

В учебнике также говорится, что техпису обычно приходится комбинировать эти принципы — например, разделы идут по логике одного принципа, а внутри разделов изложение может строиться на другом принципе.

Со своей стороны могу подтвердить верность этого наблюдения. В частности, я недавно делал тестовое задание на 500 слов про направления в дизайнах мобильных приложений, и там для общей схемы документа потребовалось применить ко всему документу систематизацию (принцип №4) направлений, а в подразделах — ранжирование характеристик направления по их важности для заказчика (принцип №5).

Как-то так. Надеюсь, эта инфа оказалась полезной не только мне. Если что, извините за потраченное время :).

ссылка на оригинал статьи https://habr.com/ru/post/721352/