Может ли техническое письмо быть менее отстойным

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

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

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

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

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

Этот вопрос затрагивает одну из центральных идей технического письма: тематическое авторство .

Ваш пример парадигмы: «1. подключите 2. подключите 3. смотрите». является образцом темы «задача», но есть также (как минимум) 2 других типа, а именно «концепция» и «ссылка».

Добавление краткой концептуальной темы, описывающей преимущества выполнения шагов 1-3, было бы более увлекательным и полностью относилось бы к компетенции технического письма.

Техническое письмо направлено на то, чтобы принять точку зрения «пользователя», что бы он ни «использовал». Так что у него есть потенциал, чтобы быть очень творческим и творческим.

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

Я в основном согласен с @mbakeranalecta, но я бы мягко оспорил идею о том, что читатель всегда занят задачей, которую вы в настоящее время объясняете - часть работы по написанию справки или часто задаваемых вопросов состоит в том, чтобы помочь читателю понять, в чем проблема (проблемы). на самом деле пытается решить; чем сложнее тема, тем труднее определить пробел в ваших знаниях и тем больше воображения потребуется, чтобы доставить читателя «оттуда» к «сюда».

Я думаю, что вы упускаете то, что все написанное рассказывает историю. То, что в тексте нет истории любви или автомобильной погони, не означает, что ваше техническое письмо не рассказывает историю. Вы просто рассказываете историю подключения Chromecast. На самом деле это захватывающая история для людей, которые только что приобрели Chromecast. Это ваши персонажи! Не уменьшайте их волнение дерьмовым письмом. Волнуйтесь вместе с ними — мы Chromecasting! — так же, как вы заволновались бы вместе с вымышленным героем, который влюбляется или переживает какое-то приключение.

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

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

Я согласен с @mbakeranalecta в том, что цель технического письма — не развлекать, а информировать.

Я вспоминаю учебник по разработке программного обеспечения, который был у меня в колледже, где текст регулярно прерывался небольшими рассказами о «первом дне Салли как программиста» и тому подобном. Эти рассказы, по-видимому, предназначались для того, чтобы оживить текст и проиллюстрировать цитаты из главы. Лично мне просто стало стыдно за автора. Истории были не только в основном неуместными, но и хромыми и приторными. «О, как интересно работать в реальном мире разработки программного обеспечения! — воскликнула Салли». Это было просто глупо.

Тем не менее, я думаю, что было бы неплохо время от времени прерывать скуку сухого материала. Я написал книгу с базой данных, в которой я попросил карикатуриста нарисовать для меня несколько карикатур, которые, Я ДУМАЮ, не были глупыми, может быть, по одной на каждую главу или две. Однажды я написал руководство пользователя, где в разделе, описывающем, как добавлять и удалять пользователей из системы, я ввел раздел о том, как восстановить удаленного пользователя, сказав: «Если вы удалите пользователя, а затем он будет ползать, прося его вернуть старую работу, вы можете восстановить пользователя с помощью ..." Ладно, это не та шутка, которая заставит людей расхохотаться, но я подумал, что это стоило того, чтобы посмеяться, и помогло поднять настроение. Я думаю, что такая вещь полезна.

Но я был бы очень осторожен, чтобы не переборщить с такими вещами. Одна маленькая шутка каждые десять страниц может поднять настроение. Даже если шутки не очень удачны, читатель, вероятно, не будет возражать. Это перерыв. Но если вы будете делать это постоянно, читатели в конце концов скажут: «Эй, я пытаюсь научиться управлять Foobar, а не слушать кучу ваших глупых шуток».

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

Скажем, я хочу подключить свой DVD-плеер к моему новому телевизору с плоским экраном. Я не хочу слышать о том, как твой дед испортил цвет, когда RCA представила его. Как это поможет мне выполнить задание? Вот критерии технических документов в порядке важности:

Это точно? Он завершен? Это уместно?

Придерживайтесь задачи и фактов. Если вы новичок в игре, найдите хорошего редактора, желательно разбирающегося в этой области, и обратите внимание на его комментарии.

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

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

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

• Используйте хороший дизайн, который делает документы легко читаемыми и эстетически привлекательными.
• Добавляйте изображения (и/или видео), чтобы визуализировать вещи
• Проблема с юмором в том, что не все его ценят. Но, если вы хорошо знаете свою аудиторию, я думаю, что нет ничего плохого в каламбуре или комиксе время от времени, если они подходят, например: https://pbs.twimg.com/media/DldA_cIXgAADj5w.jpg
• Еще один пример лаконичности и забавности — технические заметки. Техника может пригодиться для шпаргалок
• Добавьте аналогии и изображения, чтобы объяснить вещи. Пример: введение в HTTP/2 для оптимизаторов.

• Источник: https://xkcd.com/293/
• Лицензия: https://xkcd.com/license.html

Если у вас есть опыт программирования, взгляните на Кернигана и Ритчи .

Я клянусь, что половина причины, по которой Unix стала такой популярной, заключалась в поистине удивительном качестве этой книги и нескольких других, подобных ей! Я знаю, что это определенно вдохновило меня!

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

Многие программисты просто не хотят тратить время на объяснение вещей низшим существам, или им это очень сложно.

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

Кроме того, вы, вероятно, не стали бы работать над ним, если бы не понимали, какие проблемы он решит и почему вы захотите его использовать. Подобные вещи предполагаются программистом еще до того, как они начнут разрабатываться, и становятся несколько неосознанными или «очевидными».

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

Если вы представите слишком мало, то некоторые читатели будут потеряны или неправильно направлены (см. Много вопросов SE, где люди спрашивают об этих милых маленьких цепочках тарабарщины, которые на самом деле являются форк-бомбами - некоторые из которых уже разбили компьютер ОП.)

Если вы представляете слишком много, люди перестают читать, чувствуют себя оскорбленными, теряются в не относящихся к делу деталях или бормочут вам что-то о TL;DR!

Это очень особенное (хотя обычно невоспетое и недооцененное) достижение написать что-то таким образом, чтобы кто-то, кто читает это, ушел от этого со словами что-то вроде «Я не знал, что это может сделать это!», «Я могу не ждите, чтобы попробовать это самостоятельно!, или "Теперь, я вижу!"

У вас может не быть драконов, чтобы убить их, но если вы можете заставить кого-то чувствовать себя достаточно уверенно, чтобы даже приблизиться к монстру, такому как Gimp или inkscape (такие вещи я обычно держу в шкафах, которые я боюсь открывать!), тогда это большое дело.

Существует огромное пространство для технических писателей, которые действительно могут объяснять и учить, а не просто документировать!

Один из способов, который я использую, — это немного пошутить между ними. Типа 1. Включите. 2. Сделайте это снова, на этот раз вверх ногами, вы поняли. 3. Подключиться. 4. Смотреть.

Берджесс использовал что-то подобное в Earthly Powers . Главный герой схватил искусственную ногу, и Берджесс описывал, как он обращался с ней как с оружием (технический момент), а затем он сказал, что это было похоже на то, как будто он был продавцом искусственных ног и думает что-то вроде «Вот, леди, посмотрите на качество». эта нога, лучшая нога, которую ты найдешь», а затем замахивается ею на кого-то. (Это не точная цитата.)

Или вы можете написать какое-то описание между ними, например

X читал руководство '1. Подключи», — сказал он. X подключил его. «Хорошо. Следующий шаг сейчас: 2. Подключиться». 'Все в порядке! Подключим...'

и т.д.

Это то, что вы можете сделать довольно легко и сохранить интерес читателя.

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

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

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

Попробуйте подумать о ситуации, в которой находится ваш читатель. Он разочарован тем, что не может заставить что-то работать? Или они в восторге от того, что у них появилась новая игрушка? Настройте свой голос и тон в соответствии с вероятной ситуацией. Возможно, вам даже придется настроить свой тон на протяжении всего руководства. Например, введение может быть бодрым и восторженным, но раздел устранения неполадок может перейти в более сочувственный тон.

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

Если я хочу, чтобы мой папа что-то объяснил мне, может быть, мне нужны дополнительные подробности, чтобы я мог научиться делать это самостоятельно. Если я хочу, чтобы врач мне что-то объяснил, я ожидаю более технического языка (на самом деле, если бы это было слишком упрощенно, я мог бы не доверять врачу!) это сделано - полные предложения, но никаких дополнительных лакомых кусочков о том, почему это работает.

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

Руководство по голосу и тону MailChimp — отличное место, чтобы начать писать подобным образом.

Здесь много отличных ответов. Один из лучших примеров творческих руководств пользователя, с которыми я столкнулся в последнее время, это: http://jamhub.com/docs/JamHubOwnersManual_English.pdf .

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

Показывает, что возможно, когда вы думаете о своей аудитории!

Надеюсь, это поможет.

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

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

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

Я рекомендую вам прочитать эту статью — « Как улучшить вашу техническую документацию », чтобы узнать больше по этой теме.