Практические советы Стивена Кинга для технических писателей

Представляем вашему вниманию статью Рикки Эндсли (Rikki Endsley), менеджера по сообществу Opensource.com, ранее работавщую над продвижением идей свободного ПО в Red Hat. Статья посвящена основным принципам технического документирования для широкой аудитории.

---

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

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

• дать пользователям вашей разработки знать об исправлении ошибки или обновлении безопасности;
• сообщить об обновлении статуса проекта менеджеру;
• рассказать разработчикам о новом процессе утверждения патчей;
• информировать прессу о последнем релизе программы.

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

Кто ваш читатель?

Перед тем, как вы начнёте писать, отступите и убедитесь, что вы верно определили свою аудиторию. В общедоступной платформе образования Государственного университета Колорадо, Writing Studio, Мишель Мураски (Michel Muraski) выделяет три категории:

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

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

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

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

Читатели Opensource.com, например, могут быть непрофессионалами, управленцами или экспертами. Мы можем предположить, что наши читатели интересуются открытым программным обеспечением, коммуникациями или методологиями, но мы не можем предположить, что все они опытные разработчики. Если у нас есть статья, где упоминаются, например, микросервисы, то мы не можем рассчитывать, что все читатели будут знать, что это означает, поэтому нам необходимо предоставить определение или ссылку на соответствующий тематический ресурс. С другой стороны, нам нет необходимости объяснять понятие в документации для любого человека, читающего статью с заголовком «Когда вашей документации требуются скриншоты?», потому что мы можем предположить, что её будут читать только те люди, которые пишут или интересуются документацией (для получения лучших советов о том, как писать документацию к проекту, прочитайте «RTFM? Как писать документацию, которую будут читать»).

Стивен Кинг о писательстве

Итак, вы определились с аудиторией. Но садиться писать ещё рано. Вместо этого запаситесь чашечкой кофе или закуски и читайте дальше.

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

1. Хорошее писательство требует чтения

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

Стивен Кинг

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

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

После того, как закончите чтение и получите представление об ожидаемом результате, выделите минутку, чтобы подумать над тем, как ваш контент может быть использован повторно. Если вы планируете писать об одном и том же для нескольких категорий пользователей – держите это в голове в процессе работы с текстом. Например, когда разрабатывала лекцию для LinuxCon Europe, «Как говорить на их языке: Как писать для технической и нетехнической аудиторий», я поняла, что создание статьи по этой теме сделает планирование лекции проще. Если бы я сначала планировала свою лекцию, то вряд ли бы вернулась к написанию такого длинного текста (в данной ситуации, статьи) позже. В каждом случае исследование необходимо было провести одно и то же, но один подход (написание статьи, а затем лекции) — более эффективное использование времени, чем другой (написать лекцию… так и не подступившись к написанию статьи). Решив, что в дополнение к конференции LinuxCon я должна написать для читателей Opensource.com, я обратилась к участникам нашего сообщества, и они помогли мне решить, что написать сначала, а что потом.

Пример: Писательство для экспертной аудитории (разработчики)

Грегу ДеКёнигсбергу (Greg DeKoenigsberg), вице-президенту сообщества в Ansible (популярная свободная утилита автоматизации), необходимо было дать знать разработчикам о новом процессе, так что он написал объявление в рассылку для разработчиков. В своём сообщении, «Новый процесс одобрения для новых модулей в Extras», ему не требовалось давать определение для Extras, потому что подписчики рассылки ansible-devel уже должны быть знакомы с этим термином.

 

Сообщение Грега в списке рассылки также хорошо подойдёт для записи в блог разработчиков Ansible.

Пример: Писательство для непрофессиональной аудитории (сообщество)

Робин Бергерон (Robyn Bergeron), архитектор сообщества в Ansible, написала о том же изменении процесса, но для более широкой аудитории сообщества. В своей записи «Модули Ansible Extras + Вы: Как вы можете помочь» для блога целевая аудитория Робин состояла не только из участников списка рассылки разработчиков Ansible, так что она в явном виде определяет свою аудиторию в первом предложении:

 

Это приводит нас ко второму уроку от Стивена Кинга.

2. Приглашайте читателя

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

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

Стивен Кинг

Сильное вступление также поможет вам, писателю, сохранить концентрацию на вашей цели и аудитории.

3. Рассказывайте историю

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

Когда вы пишете историю, вы рассказываете историю себе. Когда вы переписываете, ваша основная работа — выкинуть всё, что не является историей.

Стивен Кинг

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

4. Уберите скучные части

Когда люди спрашивают меня, насколько длинной должна быть статья, то ответ — настолько длинной, насколько необходимо. Если ваш текст не ограничен по объёму (например, одна печатная страница журнала), количество слов весьма нежёсткое. Но если вы увидите, что ваша техническая статья имеет объём больше 1 000 слов, или обновление проекта более 500 слов, перечитайте свой текст, чтобы увидеть, нет ли в них случайно скучных частей. Кинг говорит, что необходимо их удалить.

Обычно когда я думаю о темпе повествования, я возвращаюсь к Элмору Леонарду (Elmore Leonard), который объяснял это просто блестяще, он говорил, что он просто выкидывает скучные части. Речь идёт о вырезании текста для увеличения темпа, и это то, что большинство из нас в конце концов должны делать (убивайте своих любимцев, убивайте своих любимцев, даже если это разбивает ваши эгоцентричные маленькие сердца бумагомарателей, убивайте своих любимцев).

Стивен Кинг

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

Например, запись Грега в список рассылки ansible-devel не включает подробностей о разработке модулей. Вместо этого он предлагает ссылку на руководства по модулям. В конце концов, он писал не для аудитории разработчиков модулей Ansible, так что мог опустить эти скучные части.

В приведённой записи блога для более широкой аудитории сообщества Ansible, Робин предложила краткую вводную часть:

Ребята, которые следят за множеством репозиториев Ansible, возможно, уведомлены, что ваше дружеское соседство с командой сообщества Ansible… столкнулось с очень большим отставанием в рассмотрении проблем и запросов на пуллы, особенно в репозиториях модулей… Одна из основных проблем, которые мы обнаружили – это просто узкие места в процессе…

Начав с описания проблемы, она объясняет решение:

И поэтому: Был рождён новый процесс. Я советую вам прочитать подробности, особенно если вы заинтересованы в помощи с обзорами или готовы к взаимодействию с Ansible, которое было обрисовано Грегом в пятницу в почтовых рассылках ansible-project и ansible-devel. Это говорит о важных моментах…

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

План документа

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

Новости или анонсы для сообщества:

• Введение (пригласите читателя)
• Краткая вводная информация (обозначьте проблему)
• Сообщение новостей (объясните решение)
• Заключение (включите важные даты и действия)

Техническая статья, учебное пособие или доклад:

• Введение (пригласите читателя)
• Краткая вводная информация (обозначьте проблему)
• Сообщение новостей (объясните решение)
• Технические детали (шаги для решения, ЧаВо)
• Заключение (включите важные даты и действия)

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

Советы в статье «Как заботиться и кормить прессу» включают совмещение фактических данных с пресс-релизом, но список фактов для включения в текст также хорошо работает для обновлений проектов и объявлений. Фактические данные должны включать:

• Что за продукт
• Когда он был выпущен в релиз
• На каких платформах работает
• Какие требования к конфигурации
• Сколько он стоит
• Контакты для прессы
• Ссылки и другая контактная информация для широкой публики

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

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

5. Редактура — святое

Писать — человеческое, редактировать — святое.

Стивен Кинг

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

Теперь вы определились с тем, что писать, о чём и для кого вы пишете. Вы завершили своё исследование. Вы набросали заключение. И вы знаете, как лучше всего отредактировать то, что написали. Что дальше?

6. Начинайте писать

Самый страшный момент — перед самым началом. После этого всё может быть только лучше.

Стивен Кинг

Источник: Stephen King’s practical advice for tech writers

Тэги: качество контента, навыки, опыт, организация работы, советы