Как улучшить написание записей для блога и технических статей

19.11.2015

Диа Ривз, редактор из Microsoft, делится своими советами с писателями, которые ведут технические блоги и пишут публикации для технических изданий. Советы основаны на её восприятии современных тенденций в ИТ-области, и они будут полезны широкому кругу документаторов.

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

Давайте послушаем… группа вздыхает…

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

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

Делайте это дружественно, но не чересчур

Сленг — часть нашего повседневного общения. Но запомните, что скорее всего, более 50% ваших читателей — не носители английского языка — и миру в целом не знаком наш английский жаргон. Использование сленга может сделать написанное трудным для понимания, так что если вы хотите, чтобы ваши читатели заинтересовались вашей статьёй, лучше его избегать. Переводческие машины не помогут, и забудьте о качественной локализации.

Используйте скриншоты, но умеренно

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

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

Добавляйте прямоугольники или стрелки на свои скриншоты, чтобы быстро обратить внимание пользователей на то, что они должны увидеть. Мне нравится, как этот автор предположил, что пользователи могут найти Прикрепить на панели команд, и он использовал скриншот, чтобы подсветить место, где можно найти команду Прикрепить пустой диск (которая не совсем заметна внизу экрана):

Подумайте о едином источнике

Единый источник — это когда у вас один ключевой документ, который определяет определённую возможность или функцию (например, как установить операционную систему). Потом вы ставите ссылку на этот ключевой документ везде, где вам требуется определить эту возможность или функцию, например:

Эта статья подразумевает, что вы уже установили свою операционную систему. Если нет, см. статью «Как установить Windows Server 2012 R2».

Почему единый источник?

• Единый источник сохраняет ваше время. Необходимо поддерживать и обновлять только один документ, так что контент всегда остаётся свежим.
• Число потенциальных ошибок снижается, потому что корректировки совершаются только в исходном документе.
• Нет недопонимания. Единый источник предлагает читателям единую хорошую отсылку для реализации задачи.
• Контент в ключевом документе был проверен.
• Вы не беспокоитесь об обновлении инструкций в каждом документе!

Наблюдайте за своим настроем

Определите, с каким настроем вы хотите высказаться. Когда я редактировала документацию для ИТ-профессионалов, команда использовала второго человека (вас). Мы хотели дать понять ИТ-профессионалам, что предоставляем действия, которым они должны следовать.

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

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

Не сбивайте читателя использованием нескольких разных местоимений вместе, например:

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

Лучше так:

Я могу использовать командлет Clear-Disk для удаления ключа, но я собираюсь указать номер диска, который уникален для устройства, которое я хочу отформатировать.

Относитесь к своим читателям хорошо

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

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

Уфф… Не знаю, как у вас, но мои мозги отключились после четвёртой запятой.

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

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

— Улучшения результатов онлайн-поиска

— Оптимизации контента и рекламы, которую видим онлайн и офлайн

— Повышения эффективности своих автомобилей во время движения

— Отметки людей в наших огромных коллекциях цифровых фотографий

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

Закопайте стиль спецификации

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

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

Вот немного прекрасного отрывка из спецификации:

Суперумная мышь Contoso будет работать на двух батарейках AA.

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

Вставьте две батарейки AA в вашу суперумную мышь Contoso, нажав на красную точку на обратной стороне мыши…

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

Будьте хорошим членом команды

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

Вы профессионал и хотите, чтобы документация вашей команды была связной, так? Быть хорошим членом команды означает, что вы используете руководства по стилю. Если вы создаёте статьи для сайтов Microsoft, обратите внимание на Руководства по стилю Microsoft. Если вы работаете не в Microsoft, то ваш начальник или представитель должен знать, где расположено руководство по стилю.

Следите за использованием аббревиатур

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

Правильный путь представить аббревиатуру — это расшифровать её при первом упоминании и указать аббревиатуру в скобках, например:

• Инфраструктура как сервис, infrastructure as a service (IaaS)
• Доменные службы Active Directory, Active Directory Domain Services (AD DS)

Руководства по стилю и официальные сайты содержат информацию по правильному использованию аббревиатур. Что касается Microsoft, вы можете найти утверждённые аббревиатуры в Term Studio.

Попросите кого-то это прочитать

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

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

Если вы рецензент, копайте! Делайте предложения. Вы не оказываете своим чтением какую-то милость, окидывая взглядом статью и давая комментарий: «Выглядит хорошо, дружище».

Чтобы показать, как просто опубликовать ошибки в тексте, посплетничаю о себе…

В моей самой первой записи для блога, The Scripting Editor Tells All, я написала:

…это должно быть понятно, кратко и последовательно. И что делать? Следовать тем трём домам правильного редактирования!

Вы это видите?

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

Да уж. Это было неловко.

Источник: Improve Your Writing for Blogs and Technical Articles

Тэги: блоги, командная работа, опыт, редактирование, стиль