что такое технический текст примеры
Как написать технический текст?
Эта статья-рассуждение, в которой я постараюсь рассказать, как я пишу технические тексты, покажу с какими тонкостями и нюансами мне приходилось сталкиваться при работе над узкоспециализированными статьями для коммерческих и контентных веб-сайтов. Приведу некоторые особенности и рекомендации по написанию технических текстов.
Эта статья — мой начальный опыт работы в копирайтинге и предваряет новую статью по особенностям и структуре технических текстов. Читайте.
Любой продукт имеет свою техническую составляющую. Не будем говорить о строительных материалах, инструментах, технических процессах и прочих подобных предметах, а возьмем, к примеру, духи, они имеют свою ольфакторную пирамиду с определенными составляющими, которые могут быть интересны пользователю. При чтении описания читатель получит не только красочное описание духов, но и узнает, чем обусловлен сказочный аромат. Правильная подача технической информации, как для веб-сайтов, так и для продающих компаний стоит, отнюдь, не на последнем месте.
Важно : для написания статей, касающихся технических описаний, изучать инструкции, документацию, руководства, а в некоторых случаях, ГОСТы, в них наиболее четко прописаны технические условия, характерные для услуги или изделия.
Но как для веб-сайтов, так и для продающих компаний текст должен быть написан для людей, информация должна быть подана живым языком, возможно, в некоторых случаях, для большей наглядности даже с употреблением некоторых элементов разговорной речи. Написание технических текстов — очень сложная задача, которую может выполнить далеко не каждый, даже виртуозно владеющий слогом копирайтер. Зачастую, только одного умения написать техническую статью бывает недостаточно, требуется знание технического процесса, профессиональные навыки, нюансы производства, бывает нужно привязать к статье собственный опыт, привести практические примеры.
Для написания статей придерживаются необходимых рекомендованных правил размещения и соблюдения структуры логического построения текста.
Техническая статья категорически не допускает неточности, в то же время, если вы используете понятную для специалиста инструкцию, должна быть для обычного пользователя, переведена на человеческий, доступный для понимания, язык. Автор должен изложить суть статьи доступными словами, которые могут быть поняты рядовым посетителем сайта и в то же время, в ней должна быть исключена двоякость понимания. Нельзя при этом забывать об уникальности текста.
Написание SEO-оптимизированных технических текстов требует от копирайтера огромной ответственности. Ошибки должны быть полностью исключены, информация должна быть подана точно и правильно. Иногда в этом деле помогает набор проверенных инструментов.
Рекомендации для написания технических текстов
Несмотря на то, что подача технического материала осуществляется доступным понятным языком, в целом стиль должен быть официально-деловым. Это подразумевает стандартное расположение материала. Желательно исключить из текста эмоциональные речевые выражения, предпочтительно использование профессиональных терминов, с пояснениями. Слова должны подаваться прямым порядком, необходимо использовать отглагольные существительные.
По мере написания статьи автор должен анализировать написанное, чтобы исключить двоякое понимание или домысливание текста читателем.
На основании изучения опыта других копирайтеров постарался вывести для себя алгоритм написания статей и поиска информации. Более подробно в этой статье.
Структура технического текста
Прежде всего, структура подразумевает логическое расположение материала. В этом случае читатель статьи с легкостью найдет интересующую его информацию. В техническом описании последовательно указывается процесс создания изделия, материал изготовления, его свойства, изменения и т. д. Лучше всего, если описания, например, технических процессов будут приведены к единому стандарту.
Характер подачи материала должен быть выполнен в адекватной манере изложения. Желательно статью писать в повествовательной форме, от третьего лица, доброжелательным языком. Обращения к читателю необходимо полностью исключить.
Прежде всего, текст должен носить сугубо информативный характер без эмоциональных оценок, без метафор и каких-либо олицетворений.
Целевая аудитория web-сайта
Текст должен быть ориентирован на определенную целевую аудиторию сайта. Технические тексты пишутся в зависимости от категории пользователей. Возьмем, к примеру, интернет-магазин, занимающийся распространением светотехнической продукции, допустим люстр. В этом случае, желательно чтобы информация, например, о светодиодных лампах, была понятна женщинам, делающим выбор люстры или светильника для своего дома, ведь именно они являются главными посетителями такого сайта. Однако, даже красивое продающее описание для сайта интернет-магазина должно нести техническую информацию. материал, положительные качества цвета плафона, тип лампочки, предназначение и область применения, показатели освещенности. Это важно, любая женщина оценит полезность материала и сделает выбор.
Например, тот же сайт по светотехнике, но уже описание лампочек для автомобильных фар. Это информация должна нести больше конкретики, преимущества и недостатки, область применения. В каких именно фонарях используются лампы: для габаритов, для дальнего света, для салона и т. д.
Терминология
Техническим текстам свойственна одна и, пожалуй, главная особенность — использование специальных терминов. В тексте необходимо дать точную формулировку и правильно объяснить термин.
Профессиональная терминология должна выдерживаться определенного, в начале текста введенного порядка, не следует заменять термин синонимом или пояснительным словосочетанием, заставляя читателя задумываться над словом, вводя его в заблуждение. Зачастую, для перевода технического термина приходится пользоваться специальным словарем.
Чтобы написать технические тексты копирайтер иногда досконально изучает дополнительный материал, чтобы только понять один определенный, специальный термин в статье, касающийся, казалось бы, несущественного, но, тем не менее, важного элемента.
Оформление текста
Графическое оформление должно улучшить восприятие текстового документа. Чертежи, рисунки, таблицы, графики обязательно должны присутствовать в тексте. Сплошной текст, каким прекрасным бы он не был, воспринимается читателем очень тяжело и способен удержать посетителя сайта только в случае крайней необходимости и исключительности подаваемого материала. Если на соседнем сайте найдется похожий контент, разбавленный рисунком, посетитель уйдет с этого сайта туда, ведь там текст воспринимается легче, там есть за что зацепиться глазом, там рисунок наглядно поясняет текстовый документ.
Это далеко не полный список рекомендаций для написания технических статей для веб-сайтов, но выполнение хотя бы части из них способно существенно повысить качество технического контента. Использование строгого сухого стиля или разбавление текста живыми оборотами, примерами или другими особенностями зависит от технического задания, предоставленного заказчиком и от общего характера сайта, но в любом случае только в силах автора сделать текст востребованным как пользователями, так и поисковыми системами.
Как заказать технический текст и не получить структурированное г. с картинками
Даже технически грамотный копирайтер может запороть задание так, что исправлять будет нечего. По себе знаю. Проще заново переписать.
Ситуации:
А еще копирайтеры присылают обзоры вместо инструкций, тексты для карточек товаров вместо описания категорий и еще много всего вместо того, что нужно. Как этого избежать? Отправьте автору подробное задание, в котором будут не только требования, но и подсказки.
Составление подробного ТЗ занимает время, зато ускоряет написание, проверку, внесение правок и доработку текста. И помогая копирайтеру (а грамотное ТЗ — это реальная помощь), вы в первую очередь помогаете себе.
Дайте материалы для подготовки
Можете доверить поиск информации автору, но на это уйдет дополнительное время. И где гарантия, что исполнитель найдет именно те данные, которые нужно указать в тексте? Недостаток исходной информации и ошибки в поиске — верный путь к появлению текста «не о том». Да, в этом случае вся вина ложится на плечи автора, но кто вернет потерянное время?
У вас наверняка найдется техническая документация, которой нет в сети. И готовый список ссылок на материалы, статьи и видеозаписи по теме. Чтобы разобраться с этой базой, понадобится немало времени, а уж чтобы самостоятельно найти информацию в открытых источниках и не запутаться — втрое больше.
Пример текста без дополнительной информации
Задание: описать смазку для опалубки Эмульсол-М, ее отличия от Эмульсола А, преимущества.
Вроде бы задача простая, но, когда копирайтер ищет информацию по смазке серии «М», находит только общие фразы. Средство новое, в сети пока нет информации. Копирайтер либо обращается к заказчику за подробностями (и это лучший вариант), либо пытается написать самостоятельно. Во втором случае вы получите примерно такой текст:
«Смазка для опалубки Эмульсол М — новое поколение разделительных смазок для форм. Состав обладает лучшими характеристиками и обходит предшественника Эмульсол А по диапазону рабочих температур, сочетанию вязкости и текучести. Но главное — Эмульсол М менее токсичен. Средство состоит из минеральных масел с присадками для создания прочной пленки на поверхности без образования луж жидкости на горизонтальной плоскости. Состав не вступает в реакцию с бетонной смесью. Поверхность получается ровной, без инородных включений и специфических запахов.»
Видите? Копирайтер работал с обычными техническими характеристиками без уточнений и подсказок. Польза от текста есть — он показывает, что произошли важные изменения. Но делает это водянисто, без конкретики. Из описания понятно: серия «М» лучше серии «А». Но почему?
А теперь посмотрим на текст, который мог получиться у копирайтера, владеющего полной информацией:
«Разработчики новой версии Эмульсола учли недостатки прошлого состава и создали универсальное средство, которое подходит для нанесения на металлическую, деревянную, пластиковую и фанерную опалубку. Список изменений состава и характеристик смазки:
В результате новый Эмульсол М облегчает извлечение готовых деталей, не портит поверхность, защищает материал опалубки и сохраняет свойства в 2-3 раза дольше прототипа.»
Подробности улучшили описание, сделали его более понятным. Копирайтеру удалось развернуть материал, структурировать его. Но такая работа часто возможна только при плотном взаимодействии с заказчиком. Например, в случае с эмульсолами (это почти реальная ситуация) сведения о влиянии состава на свойства найти почти невозможно. Даже о старом средстве данных маловато, а чтобы сравнить его с новым — вообще ничего. Эту информацию даст только производитель. Владельцы редко выкладывают инструкции и описания в сеть. Найдите пару минут и поделитесь знаниями с исполнителем!
Данные, которые точно пригодятся копирайтеру:
При отправке подробных сведений и дополнительной информации вы экономите время копирайтера на поиск и свое — на проверку. Автор сразу начинает с изучения достоверных данных, а не с поиска крупиц истины в интернете.
Покажите, как нужно и как не нужно писать технические тексты для вашего ресурса
У вас есть собственное видение «хорошего» текста. Поделитесь им с исполнителем. Только обязательно — с подробностями. Например, если прикладываете к заданию примеры хороших текстов, покажите, что именно в них нравится. Иначе может получиться два разных взгляда на один текст:
Обратите внимание — в чем-то взгляды автора и заказчика сходятся, но обычно все мы видим в текстах что-то свое. Еще хуже понимаются примеры того, как писать не нужно — здесь ответы сходятся вдвое реже. Чтобы избежать недопонимания, объясните копирайтеру, что именно вам нравится и не нравится в тексте.
Хотите с первого раза получить текст с нормальной структурой? Потратьте 5 минут на оформление этой части ТЗ в виде картинок с пояснениями (как на примерах выше) или как ссылки на страницы с комментариями:
Проверьте план, по которому работает копирайтер или пришлите собственный
Планы страниц в едином стиле — первый шаг к составлению собственной редакционной политики. Это очень полезно при создании многостраничных технических ресурсов. Такие тексты выглядят более профессиональными, страницы сайта однотипны и похожи на части большого документа, энциклопедии. Примеры планов для технических текстов:
I. Базовый план для описаний сложных технических товаров
II. Базовый план для описания категорий
Структура похожа, но речь уже не о товаре, а о группе продуктов. Здесь приводятся краткие описания пунктов или упоминаются как примеры отдельные товары:
III. Базовый план описания технически сложной услуги
(например, контроль соединений, аттестация персонала, разработка проекта, диагностика оборудования)
Похожие шаблоны можно составить для каждого типа текста, который используется на сайте. План помогает структурировано подавать материал, исключает разнородное наполнение страниц и облегчает работу с копирайтерами.
Укажите, для кого пишется текст
Эта общая рекомендация для всех текстов в применении к техническим статьям становится еще более важной. Посетители сайтов с техническими текстами делятся на 3 группы:
Написать один технический текст для новичков, опытных пользователей и профессионалов не получится. Да это не нужно — на сайте обычно собирается только один тип аудитории. Выясните, какой именно, внесите корректировки в базовые планы текстов и обязательно сообщите правила написания копирайтеру.
Укажите назначение будущего материала
Для вас назначение текста очевидно, для копирайтера — не всегда. Технический текст может быть описанием товара или услуги (продающим или информационным), материалом для буклета, инструкцией, обзором.
Пример назначения материала:
Текст с описанием предпускового подогревателя Бинар-5С.
Страница, на которой будет размещен текст: http://mysite.ru/razdel/podogrevatel-binar-5c.
Текст будет располагаться под моделью подогревателя. Внизу страницы – цены на разные модификации. В тексте нужна краткая инструкция по установке и использованию.
Используйте шаблон для составления ТЗ копирайтеру
Готовый шаблон поможет ничего не упустить при составлении задания.
Итак, вот что желательно включить в текст ТЗ:
Не рубите сгоряча
Даже подробное ТЗ не гарантирует, что текст с первой попытки устроит по всем параметрам. Стадия правок и доработки бывает в 90 % случаев работы с техническими текстами. Особенно, если заказчику не безразлична судьба проекта.
Ошибки в технических текстах обычно связаны с недостаточным погружением в тему — согласитесь, за несколько дней подготовки невозможно изучить вопрос во всех подробностях. Поэтому заключительная рекомендация заказчику технических текстов — подробно указать на все недочеты. Для удобства воспользуйтесь тем же документом: выделите и прокомментируйте спорные места, а потом отправьте материал на доработку.
Такой подход к составлению ТЗ и работе с техническими текстами отнимает больше времени, чем лаконичные заказы и не менее лаконичные отказы. Но время потрачено не впустую: вы получаете качественный вариант (сразу или после небольшой доработки), а в довесок — автора, который уже знаком с вашими требованиями и в следующий раз напишет текст быстрее и лучше.
В Google и «Яндексе», соцсетях, рассылках, на видеоплатформах, у блогеров
Значение технического текста
Содержание:
Что такое технический текст:
Технический текст представляет собой текстовая типология, которая представляет методологии или процессы, необходимые для применения и развития ряда действий или научных знаний.
В этом смысле технический текст содержит ясный, точный и последовательный дискурс, который направляет читателя на протяжении всего развития деятельности или практики, которые могут включать в себя применение чуждых ему методологий или инструментов.
Таким образом, технический текст характеризуется тем, что он описательный и наглядный, потому что он раскрывает процесс, в котором применяются различные научные знания, а также могут быть раскрыты особенности используемых инструментов.
Следовательно, технический текст обычно связан с научным текстом. Оба типа текстов представляют содержание, которое является результатом научных исследований, чтобы раскрыть и объяснить процессы и инструкции, которым необходимо следовать в различных областях человеческого развития, особенно с точки зрения науки и технологий.
В качестве примера технических текстов мы можем упомянуть, среди прочего, руководства, инструкции, каталоги.
Технические характеристики текста
Ниже представлены основные характеристики технического текста.
Научно-технический текст
Научно-технический текст передает информацию или инструкции, полученные в результате научных исследований или разработки определенных технологических приложений, с целью раскрытия указанного содержания.
В этом типе текста широко используются технические языки и коды, поэтому он обычно предназначен для конкретной аудитории, а не для общей.
Примеры научно-технических текстов включают статьи, руководства, конференции или монографии, посвященные, среди прочего, темам медицины, физики, химии, техники.
См. Также Научный текст.
Медитация как средство от фанатизма
Лекарство от сна: что это такое, как его использовали и почему не рекомендуется
7 правил написания технической документации мирового класса
Введение
Написание технического документа — трудное дело. Чтение плохо написанного технического документа является более трудным и, вероятно, более болезненным делом, чем его написание. Требуется большая работа, чтобы создать ясное, точное, интересное техническое описание. Поэтому, чтобы сделать жизнь хоть немного проще для всех участвующих сторон, я хотел бы поделиться с вами семью правилами, которым я следую, создавая техническую документацию.
Эти правила — не моё собственное изобретение. Скорее, я просто сформулировал их из того опыта, который появился благодаря общению со многими талантливыми техническими и литературными редакторами за более чем десять лет работы. Всё, что я понял в этом деле, сформировалось потому, что другие показали мне путь. У меня не находится достаточно слов, чтобы выразить им в полной мере мою благодарность.
Надеюсь, после прочтения этой статьи в вашем арсенале появятся некоторые новые инструменты, которые помогут вам создавать технические документы на новом уровне качества: более ясные, более привлекательные, менее путанные и намного более интересные для чтения. Также я добавил — без всяких каких-либо дополнительных требований к вам, как потребителю, бонус в конце статьи: описание процесса, используемого мною для создания технического описания.
1. Скука убивает
Это правило является, по-видимому, самым трудным для формализации и самым важным по необходимости соблюдения. В современном мире интернета действует много сил, борющихся за внимание вашего читателя. Скучное стандартное описание работать не будет. При любых обстоятельствах ваш читатель желает, чтобы было увлекательно и информативно. Поэтому, если ваш текст неясный или неинтересный, то читатель просто щёлкнет пресловутую кнопку «Далее» и перейдёт на другую веб-страницу или на другую ТВ-программу или на свою страницу в Фейсбуке.
Самый простой путь, который я нашёл для пробуждения интереса у читателя, состоит в том, чтобы интересно было мне самому. Я всегда прилагаю значительные усилия, чтобы написать такую статью, которую сам хотел бы прочитать. Я стремлюсь получать удовольствие от того, что пишу. Если мне скучно, то заскучает и читатель. Если я запутался, то запутается и читатель. Если меня не волнует рассматриваемая тема, то читатель, тем более, не взволнуется. Всё очень просто!
Мне нравится юмор, поэтому я стараюсь сделать мои литературные технические «творения» забавными, но, конечно, без ущерба для ясности. Пытаюсь разговаривать с читателем, а не поучать его. Пишу о делах, которые, действительно, имеют значение для меня. Широко использую иллюстрации, чтобы предотвратить неясность для читателя.
И снова, всегда стараюсь сделать процесс чтения увлекательным. Я всегда помню, что пишу в конкурентной среде. Имеется множество контента, стремящегося привлечь внимание читателей. Таким образом, мой совет по правилу № 1: если ваши тексты будут интересны вам, то они будет интересными и для читателя.
2. Прежде чем начать, выясните точно для себя, какие действия вы ожидаете от читателя, осилившего ваш труд
Техническая документация полностью завязана на последующее поведение читателя. Читатель затрачивает своё время на чтение вашего творения, потому что он или она имеет намерение сделать что-то после завершения процесса чтения. Этим «что-то» может быть выпечка печенья с кусочками шоколада, остановка ядерного реактора или разработка кластера Hadoop. Важно помнить, что читатель использует ваше описание как средство для выполнения другого процесса. Ваш труд является неким проводником к дальнейшему вполне определённому поведению.
Поэтому чрезвычайно полезно для вас чётко определиться, какие действия вы ожидаете от читателя после завершения процесса чтения. Изложите ваше намерение с самого начала. Не оставляйте читателя гадать. Ваше заявление может быть простым и очевидным, как, например: «после прочтения данной статьи вы сможете [впишите свой вариант]». Если вы определились с действиями, ожидаемыми от читателя после прочтения, то процесс написания будет для вас легче с самого начала.
3. Пишите в соответствии с правильно сформированной структурой
Хорошо сформированная структура является тем остовом, вокруг которого растёт ваш документ. Подготовка технического документа без использования некоторой структуры равносильна попытке ориентироваться в метро Нью-Йорка (469 станций!) без схемы. Вы можете оказаться где угодно, но это «где угодно» может оказаться совсем не тем местом, куда вы предполагали попасть.
Написание технической документации в соответствии со структурой не означает увеличение объёма работы. Наоборот, нагрузка уменьшается. Работая со структурой, вы знаете, откуда вы выходите и куда собираетесь прийти.
Имеются два правила структурирования, которые я всегда использую:
1. Раздел подуровня требует наличия, как минимум, одной позиции.
2. На каждом уровне структуры должно быть, как минимум, два предложения.
Хотелось бы уточнить. Листинг 1 внизу является примером структуры, которая нарушает первое правило: раздел подуровня требует наличия, как минимум, одной позиции.
Листинг 1: неправильно сформированная структура
1. Приготовление апельсиново-клюквенно-мандаринового шипучего напитка
1.1. Шаги, требуемые для приготовления шипучего напитка
1.1.1. Подготовка ингредиентов
1.1.2. Смешивание ингредиентов шипучего напитка
1.1.3. Подача шипучего напитка
Обратите внимание, что в листинге 1 уровень 1 имеет одиночный подуровень: «1.1. Шаги, требуемые для приготовления шипучего напитка«. Такая структура является нарушением первого правила. Чтобы подуровень был правильно сформирован, в разделе должна быть, как минимум, ещё одна позиция. Другими словами, это значит, что на любом данном уровне должно быть, как минимум, два подуровня.
Посмотрите листинг 2 внизу. Обратите внимание, что у уровня 1 теперь имеются три подуровня, из которых раздел «Смешивание ингредиентов шипучего напитка» содержит позиции. Одиночный уровень «Шаги, требуемые для приготовления шипучего напитка» удалён.
Может возникнуть вопрос: «Где раздел Шаги, требуемые для приготовления шипучего напитка». Видно, что этот раздел теперь не является позицией структуры, а перешёл в контент исходного раздела, как показано в листинге 2 внизу.
Листинг 2: правильно сформированная структура, нарушающая правило двух предложений
1. Приготовление апельсиново-клюквенно-мандаринового шипучего напитка
Раздел внизу описывает процесс, который надо соблюсти для приготовления апельсиново-клюквенно-мандаринового шипучего напитка.
1.1. Подготовка ингредиентов
1.2. Смешивание ингредиентов шипучего напитка
1.3. Подача шипучего напитка
Обратите внимание, что, хотя листинг 2 демонстрирует структуру с правильно сформированным подуровнем, в контенте раздела уровня 1 имеется только одно предложение. Присутствие одного единственного предложения в контенте раздела структуры нарушает второе правило структурирования — «На каждом уровне структуры должно быть, как минимум, два предложения«.
Листинг 3 показывает тот же текст, но изменённый с целью обеспечить выполнение правила двух предложений.
Листинг 3: правильно сформированная структура, выполняющая правило двух предложений
1. Приготовление шипучего апельсиново-клюквенно-мандаринового напитка
Апельсиново-клюквенно-мандариновый шипучий напиток может доставить большое удовольствие в жаркий летний день. Напиток состоит из природных компонентов без искусственных ароматизаторов. Апельсиново-клюквенно-мандариновый шипучий напиток не только вкусный, но и чрезвычайно полезный!
Разделы внизу описывают процесс, который надо соблюсти для приготовления апельсиново-клюквенно-мандаринового шипучего напитка.
1.1. Подготовка ингредиентов
1.2. Смешивание ингредиентов шипучего напитка
1.3. Подача шипучего напитка
Почему я так беспокоюсь о правильной структуре и о, по крайней мере, двух предложениях на каждом уровне? Во-первых, соблюдение правила подуровня побуждает меня быть предельно чётким в логической сегментации моего труда. Следование правилу подуровня способствует также тому, что мой текст соединяет мои идеи с общей линией, которая имеет смысл и легко прослеживается.
Во-вторых, правило двух предложений требует от меня написать текст, который является привлекательным, подробным и целесообразным. При записи в «одно предложение» нередко теряются подробности. И, если не рассматривать афоризмы, текст в «одно предложение» — не самое интересное чтение.
4. Избегайте неоднозначных местоимений
Неоднозначное использование местоимений является, вероятно, самой типичной причиной путаницы в практике подготовки технических описаний.
Рассмотрим абзац в листинге 4.
Листинг 4: абзац с неоднозначными местоимениями
Трафальгаборы являются базовой компонентой фрейма Вибитатов. Эта статья показывает, чем они являются и как их использовать.
Данный абзац выглядит, возможно, несколько комично, но он иллюстрирует некоторые важные точки. Во-первых, абзац пытается поставить вас на место, которое занимает читатель. Читатель желает понять, что происходит, но он незнаком с используемыми терминами. А поскольку термины непонятны, то читатель ощущает себя некомпетентным и потому уязвимым. Читателю нужна новая информация — он или она желает стать умнее. Но читатель также немного беспокоится. Допущение собственной некомпетентности, даже перед самим собой, даже на подсознательном уровне — может быть ему неприятно. Читатель болезненно чувствителен к пониманию представляемого материала. Понятия и слова, которые вы, лицо пишущее, считаете само собой разумеющимися, могут быть полностью чуждыми читателю. Одно плохо объяснённое понятие или одно слово, использованное без надлежащего разъяснения, могут подтолкнуть читателя прекратить чтение.
Применительно к абзацу вверху я не удивлюсь, если вы спросите: «Что это за штука „Трафальгабор“? А что такое „Вибитата“? О чём, вообще, этот абзац? О том, как использовать Трафальгаборы? Или о том, как использовать Вибитаты? Или о том, как использовать и те, и другие? Бред какой-то. Вернусь я лучше на свою страницу в Фейсбуке».
Если читатель при чтении вашего описания вынужден тратить время на выяснение, что же вы пытаетесь ему сообщить, то мало того, что информативный поток будет нарушен, но и читатель, скорее всего, будет запутан. Как только вы привели читателя в замешательство, вы его потеряли. Всё другое в мире, направленное на привлечение внимания вашего читателя, становится для него более притягательным, чем ваше творение. Щелчок по кнопке «Далее» — и ваша работа остаётся непрочитанной.
В листинге 4 замешательство порождается неоднозначным использованием местоимения «они» во втором предложении. К чему относится здесь «они» — к Трафальгаборам, Вибитатам или к обоим? Помните, что читатель ничего не знает, что такое Трафальгаборы или Вибитаты. (См. рис. 1 внизу.)
Рис. 1. Использование неоднозначных местоимений запутывает техническое описание
Решение проблемы простое. Посмотрите листинг 5 внизу. Неоднозначное местоимение удалено. Ясность восстановлена.
Листинг 5: устранение неоднозначных местоимений
Трафальгаборы являются базовой компонентой фрейма Вибитатов. Эта статья рассказывает, что такое Трафальгаборы и как их использовать.
Осторожно! Неоднозначное использование местоимений ведёт к техническому описанию, приводящему в замешательство.
5. Ясность = иллюстрации + слова
Посмотрите на фотографию внизу. Скажите, если сможете, о чём это фото?
Я не удивлюсь, если вы будете немного растеряны. Эта фотография, действительно, озадачивает. Вы знаете все отдельные компоненты, но вам неясно, что они все вместе значат. Такова природа любой иллюстрации. Картинке без слов не хватает контекста.
При обращении к иллюстрациям читателям требуется контекст, чтобы внести ясность. Недопустимо, чтобы читатель напрасно тратил время или усилия, пытаясь выяснить, о чём же рассматриваемая графика. Самым лёгким путём устранить неясность с иллюстрациями является обеспечить их надписями.
Посмотрите на рис. 2 внизу. Он представляет собой то же самое фото. Но здесь уже нет вопроса, о чём оно.
Рис. 2. Инструменты и ингредиенты, требуемые для приготовления апельсиново-клюквенно-мандаринового шипучего напитка
Применительно к техническим описаниям я считаю полезным все иллюстрации снабжать пронумерованными описательными надписями.
Не помещайте надписи, содержащие только цифры. Используйте в надписи, как цифры, так и описательный комментарий. Также не допускайте появления изолированных иллюстраций. Изолированной иллюстрацией считается такая, которая расположена в техническом описании, но ссылка на которую в тексте отсутствует.
Вставляя иллюстрацию в ваше описание, следите за тем, чтобы сослаться на неё в тексте указанием её номера и таких слов как «выше», «вверху», «ниже», «внизу». Недопустимо вынуждать читателя при чтении вашей работы тратить время на привязку иллюстрации к тексту или на её поиск в описании. Если вы добавляете в текст, скажем, «Рис. 4», то убедитесь, что где-то в тексте сказано что-то вроде «см. рис. 4 внизу».
Примечание: глаз привлекают изображения
Десять лет назад я работал в группе, которая писала пользовательское руководство (под типографское издание) для очень, очень большого изготовителя компьютеров. Все руководства подвергались формальному количественному исследованию на удобство пользования. Тогда от специалистов по взаимодействию с пользователем я узнал, что, когда человек читает руководство, глаз его идёт сначала к изображениям. Лишь затем читатель смотрит на текст вокруг этого изображения. Поэтому авторы того руководства пытались обеспечить, чтобы на каждой его странице была хотя бы одна картинка.
6. Когда имеете дело с понятиями, концепциями и т.п., используйте логическую иллюстрацию и пример, логическую иллюстрацию и пример
Понятия трудны для понимания — и это то, почему они называются «понятиями». Поэтому, когда мне приходится писать о каком-то общем положении — будь то второй закон термодинамики, компонент методики кодирования или полнофункциональная платформа программного обеспечения, я использую следующий подход в моём описании: понятие — логическая иллюстрация — пример. Я никогда не пытаюсь ввести какое-либо понятие без подкрепления логической иллюстрацией и дальнейшим примером.
Применим это правило для описания понятия элементарной алгебры.
Понятие «транзитивность отношения равенства» представляет собой следующее:
если A = B и B = C, то A = C;
Теперь приведём логическую иллюстрацию, описывающую это понятие (см. рис. 3).
Рис. 3. Транзитивность отношения равенства является фундаментальным принципом элементарной алгебры
Листинг 6 ниже показывает несколько конкретных примеров для закрепления понимания рассматриваемого положения.
Теперь рассмотрим понятие, которое ближе к разработке программного обеспечения и несколько труднее для понимания. Таким понятием является наследование моделей объектов проекта (POM = Project Object Model) в Maven (система автоматизированной сборки проектов). Пример 1 ниже представляет рассматриваемое понятие и даёт логическую иллюстрацию, описывающую это понятие. В конце представлена ещё одна иллюстрация, показывающее конкретное использование POM-файлов в ситуации наследования.
Пример 1: выдержка из технического описания наследования моделей объектов проекта (POM) в Maven (система автоматизированной сборки проектов)
Представление наследования POM-файла
POM-файл является XML-файлом, используемым для описания Maven-проекта и для работы с этим проектом. Можно задать, чтобы некоторый Maven-проект наследовал настройки из отдельного родительского POM-файла. Способность наследовать настройки из родительского POM-файла называется POM-наследованием. Вы используете элемент в вашем POM-файле, чтобы задать родительский POM-файл, из которого должно произойти наследование настроек.
Рис. 4 ниже показывает иерархию некоторого условного проекта, являющуюся примером задания мастер-файла РОМ, из которого другие РОМ-файлы могут наследовать общие настройки.
Рис. 4. Можно назначить мастер-файл РОМ, из которого будет происходить наследование общих настроек
Рис. 5 ниже показывает содержание POM.xml-фалов для Maven-проектов stooges-web, stooges-api и stooges-dal. Каждый проект сконфигурирован на использование элемента для наследования настроек из stooges-project.
Рис. 5. Использование элемента для управления Maven-проектом с целью наследования настроек из внешнего РОМ-файла
Пример выше опирается, в основном, на рисунки, чтобы обеспечить логическую иллюстрацию и показать конкретное использование рассматриваемого понятия. Подготовка интересных, привлекательных и точных иллюстраций и примеров является трудной задачей, но усилия стоят того. Создание множества иллюстраций для технического текста и примеров кода требует времени не меньше, чем написание самого текста. Соответственно я планирую моё время, чтобы выполнить работу в срок.
Итак, если требуется предельно ясно представить какое-то понятие, то необходимо включить в текст иллюстрации и примеры.
7. Не опасайтесь переделок
Редко удаётся написать хороший технический текст с первой попытки. Освоение темы, организация подходов и нахождение формы ясного и точного представления идей требует много времени и усилий. Поэтому не стесняйте себя ожиданием, что всё получится прямо с первого раза. Лучше планируйте пройти, как минимум, через три версии вашего творения. Первая версия представляет собой просто некоторый набор слов в печатном виде, давая вам возможность осознать ваши намерения. Вторая версия уже придаёт вашей работе ясность и точность. Затем, когда все факты в тексте проверены, иллюстрации выверены и структура логично выстроена, можно подготовить третью версию, которая будет привлекательной и своеобразной.
Можно сказать об этой работе, перефразируя известную цитату Томаса Эдисона: «Написание технического текста — это на 10% литературное творчество и на 90% переработка!»
Обещанный бонус
Теперь, когда вы знаете 7 правил для создания технической документации мирового класса, я хотел бы поделиться с вами изложением процесса, который я использую при подготовке технических текстов. Здесь немного, но по существу. Я называю этот процесс — ««7 шагов создания технического документа». Итак:
1. Составляю структуру, как минимум, до второго уровня (если удаётся, то и до третьего);
2. Добавляю иллюстрации в структуру для каждого понятия;
3. Делаю подписи под иллюстрациями;
4. Пишу текст в соответствии со структурой, соблюдая правило двух предложений и подстраивая структуру под текст;
5. Редактирую, переделываю;
6. Отправляю результат специалисту по рассматриваемой теме на рецензирование (специалистом по рассматриваемой теме является лицо, которое в состоянии выявить неточности и неясности в описании);
7. Снова редактирую работу на основе отзыва рецензента (рецензентов).
И вот они у вас: 7 правил, 7 шагов. Кому-то надо больше? Теперь, когда вы знаете все мои приёмы, двигайтесь свободно вперёд и делайте мир более правильным, привлекательным, ясным и интересным местом для жизни. Он заслуживает таких усилий.