Клуб технических писателей

июнь 2014
Описываем действия
Алексей
9 июня 2014, 19:59
Сообразуйте  действие с речью, речь с действием.

Шекспир, «Гамлет», акт 3, сцена 2.

 

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

Например, эти две истории различаются только стилем:

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

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


Персонажи должны быть подлежащими в предложениях

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

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

 

Сказуемые должны быть глаголами, явно указывающими на действие

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

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

 

Применяем на практике

Допустим, у нас есть предложение повышеной лохматости:

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

Как улучшить его, следуя нашим принципам? Нужно ответить на два вопроса: 

  1. Какие действия передают суть истории? В этом предложении некто решает задачу, вводит систему оценки и регулярно ее применяет, а также улучшает правила. Эти действия должны стать сказуемыми-глаголами.
  2. Какое действующее лицо подходит на роль подлежащего? В текущем виде действующего лица вообще не видно — только какое-то решение чего-то требует в белой комнате с мягкими стенами. В таком случае нужно добывать подлежащее из контекста: для поста в блоге подойдет «мы», для технического описания — название системы, которая решает задачу.

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

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

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

 

Попробуйте потренироваться на кошках в комментариях

2 комментария
яндекс,стиль
По следам Гипербатона
Полина Порохова
10 июня 2014, 16:19

 Добрый день!

24 мая в Москве прошел «Гипербатон» — наша первая конференция по технической документации. Мероприятие собрало 160 человек в зале и 60 на трансляции, среди участников были представители компаний Лаборатория Касперского, QIWI, Сбербанк, КРОК, МегаФон, Минкомсвязь России, ЛитРес, ABBYY, Acronis, Business FM, Luxoft, Oracle, Parallels, Wikimart, DOMODEDOVO INTEGRATION и др. Площадка конференции стала первым местом знакомства и живого профессионального общения технических писателей из Москвы, Санкт-Петербурга, Ярославля, Тулы, Самары, Новосибирска, Тамбова, Екатеринбурга, Ставрополя и даже Гомеля. 

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

По следам анкетирования
В нашем опросе приняли участие 139 респондентов. Все участники ответили, что готовы вернуться снова, название конференции оценили положительно 67%.

Все докладчики получили хорошие оценки за выступления, но самыми полезными по результатам анкетирования оказались доклады Юры Никулина ("Особенности документирования для разработчиков"), Насти Ванехиной ("Оценка качества документации") и Макса Горкунова ("Локализация в Яндексе: как мы это делаем").

Видео докладов уже доступно по ссылкам:
Открытие, Светлана Каюшина, Яндекс
Профессия «технический писатель»: история и современное состояние, Кирилл Маслинский, Яндекс 
Как начать документировать API, Арина Кирпичева, Яндекс 
Особенности документирования для разработчиков, Юрий Никулин, Яндекс 
Экспертиза текста в интерфейсе. Метод технического писателя, Дарья Егорушкина, «Лаборатория Касперского» 
Оценка качества документации, Анастасия Ванехина, Яндекс 
Локализация ПО и документации: опыт ABBYY Language Services, Антон Воронов, ABBYY Language Services 
Локализация в Яндексе: как мы это делаем, Максим Горкунов, Яндекс
Интерактив «Спроси у доки»

Еще раз спасибо большое всем, кто принял участие в мероприятии.
Посмотреть фотографии можно в фотоальбоме на Я.Фотках, Facebook и ВКонтакте.

Итоговый ролик Гипербатона. Вспоминаем, как это было и готовимся к следующей конференции.


До новых встреч!

2 комментария
гипербатон,посмотреть,конференция,2014
Инструменты для работы со стилем
Татьяна Грачёва
17 июня 2014, 17:03

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

Коэффициент удобочитаемости
Рядом с числовым коэффициентом обычно указывается уровень образования, который потребуется читателю, чтобы понять ваш документ.
Посмотреть статистику удобочитаемости можно стандартными средствами (см. инструкцию для MS Word) или с помощью онлайн-сервисов — например, audit.te-st.ru или readability.io.

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

Тавтологии и паронимы
Существуют сервисы и программы, с которыми можно легко вычислить тавтологии (лексические повторы), паронимы (слова, похожие по звучанию) и случайные рифмы. Это, например, десктопная программа и онлайн-сервис «Свежий взгляд».

Пользуетесь ли вы в работе какими-то из этих инструментов (или другими, подобными)? Если да, то какими?
Насколько полезны они для технического писателя?

5 комментариев
яндекс,стиль,Инструменты