У химиков есть известная байка, которую они любят рассказывать молодому поколению. Главный герой этой истории — студент, который пошагово воспроизводил методику одного химического эксперимента из учебника. Он старательно выполнил очередной шаг «добавьте азотную кислоту» и... в лаборатории прогремел взрыв! Когда впоследствии стали разбираться, в чём же дело, выяснилось, что на следующей странице учебника было написано: «... медленно, по каплям».

Примечания и уточнения — очень важный элемент любого технического и научного текста. В любом документе фрагменты текста можно ранжировать по важности и критичности излагаемых сведений. Бывает просто обычный текст, который течёт себе ровно, как спокойная равнинная река. Бывают фрагменты с дополнительной, необязательной, уточняющей информацией: автору хотелось их добавить в текст, но они плохо укладываются в основную логику изложения материала. А ещё бывают критичные замечания и уточнения, которые обязательно должны быть обвешаны мигающими сигнальными огнями, сиренами, хлопушками и прочими средствами привлечения внимания читателя.

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

Как же лучше писать и оформлять примечания? В статье расскажу вам про свои пять несложных правил.

1. Важное — вперёд

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

Читатели инструкций вполне могут выполнять шаги последовательно — один за другим. И переходить к изучению следующего шага только после выполнения предыдущего. Также не стоит рассчитывать на то, что читатели читают документ от начала до конца. Если вы разместили какое-то важное предупреждение в предыдущем разделе, не стоит рассчитывать, что его обязательно прочтут те, кто будут читать следующий раздел.

2. Типов — три

В нашей компании технические писатели пишут исходники документации в формате DITA. В этом формате для тега <note> предусмотрено целых 13 значений атрибута type: attention, caution, danger, fastpath, important, note, notice, other, remember, restriction, tip, trouble и warning. Вначале писатели честно пытались соблюдать эту типизацию — подбирать для каждого примечания соответствующий тип.

Но в какой-то момент, после очередной попытки почувствовать тонкие различия и сделать выбор между attention, warning, caution и danger, все просто забили и волевым решением сократили весь этот зоопарк типов до трёх:

• note — «Примечание» — обычное примечание, дополнение к тексту;

• restriction — «Ограничение» — информация об ограничениях работы описываемых решения, системы или функциональности;

• attention — «Внимание!» — критическая информация, на которую читатель должен обязательно обратить внимание.

Наш технический редактор внёс это решение во внутреннее руководство по стилю и все полностью избавились от проблем с выбором типа примечания. У вас могут быть свои, подходящие именно вам, типы примечаний. Главное — не переборщить с введением новых типов. Три — очень хорошее число.

3. Раскраска — светофор

Кстати, когда у вас есть всего три типа примечаний, очень легко будет выбрать дизайн их оформления. В этом случае удобнее всего будет использовать знакомую всем читателям документации метафору светофора: красный — стой, читай текст; жёлтый — обрати внимание; зелёный — можно идти дальше, если не интересно.

Наши писатели так и поступили — снабдили три наших типа примечаний рамками в цветах светофора. Правда, зелёный цвет заменили на синий. Этот цвет обычно воспринимается как нейтральный и хорошо подходит для дополнений к тексту — вроде примечание и отделено от основного текста документа, но по цвету видно, что там что-то совсем не критичное. Скорее — нечто «умное и интеллектуальное», для углублённого изучения темы.

Интересный факт: в японских светофорах долгое время вместо зелёного использовался синий цвет. Это связано с тем, что изначально в японском языке не было различий между синим и зелёным цветом, и для их обозначения применялось одно слово — аоi (青い). Позже для зелёного цвета появилось отдельное понятие midori (緑). Но по традиции зелёный свет светофора всё равно называют синим. Так и повелось, что в Японии разрешающий свет — синий (хоть и максимально приближенный к зелёному).

4. Злоупотребление — зло

Ещё одно правило — не злоупотреблять примечаниями и использовать их в меру. Если читатель на каждой странице будет видеть «красные» примечания, то очень скоро он просто перестанет обращать на них внимание. А что ещё прикажешь делать, если документ «орёт и ругается» на тебя с каждой страницы?

Если же у вас в тексте одно за другим идут сразу несколько обычных «синих» примечания, то это хороший повод задуматься, а не вынести ли их все в отдельный раздел с уточнениями и пояснениями. Просто очень тяжело читать текст, который постоянно прерывается какими-то дополнениями и уточнениями.

5. Разглагольствованиям — нет

Критические примечания типа «Внимание» — не место для многословных описаний. На дорожных знаках не пишут: «В этом месте вам обязательно надо остановиться и посмотреть направо и налево». На дорожных знаках пишут: STOP. Обратите внимание, что даже восклицательного знака там нет.

Если вы действительно хотите предостеречь читателя от каких-то действий, используйте предельно лапидарный стиль.

Чехов в шутку писал: «Не Шекспир главное, а примечания к нему». Но ведь действительно, иногда примечания бывают даже важнее основного текста. Мы знаем, что большая часть пользовательской и другой документации — это, в общем-то, формальное описание того, что и так понятно и очевидно опытным читателям. А вот примечания зачастую содержат дополнительную или важную информацию, которую пользователи могут не знать по умолчанию. Поэтому в документации примечания важнее Шекспира.