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

февраль 2015
Подпишитесь на новые публикации
Юрий
9 февраля 2015, 17:31

Дорогие друзья!

Мы с новыми силами приступаем к работе над материалами для нашего клуба. В ближайшее время будет опубликована серия статей по следующим тематикам:

  • Обзор профессиональной литературы. Продолжим рассказывать про некоторые книги из списка.
  • Конспекты докладов, с которыми мы выступали в прошлом году на Гипербатонах и YaC.
  • Личный опыт техписателей Яндекса в решении различных задач.

Мы приглашаем всех делиться своим опытом в разработке документации и писать статьи в наш клуб.

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

Нет комментариев
Чек-лист редактора документации
Татьяна Грачёва
16 февраля 2015, 15:50

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

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

Немного слов о том, как я работаю:

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

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

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

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


А это мой чек-лист

1. Представляю, что я продвинутый читатель:
    1.1. Понятна ли цель статьи?
    1.2. Вписывается ли статья в тот раздел, в котором она находится?
    1.3. Все ли понятно по сути проекта, который мы описываем?
    1.4. Структура текста:
           • Все ли в тексте логично? Одно последовательно вытекает из другого?
           • Прохожусь по инструкции. Все ли получается по ней сделать?
           • Если раздел посвящен вопросам и ответам, соответствует ли ответ заданному вопросу?
    1.5. Ссылки:
           • Ссылки работают и ведут, куда надо?
           • Ссылок хватает?
           • Нужно ли сослаться на эту страницу из других разделов справки? Если да, то из каких?
    1.6. Проверяю факты:
           • Точно ли названы элементы интерфейса, которые мы описываем?
           • Правильно ли написаны названия компаний и внешних ресурсов?
           • Доступны ли эти ресурсы? Существуют ли эти компании до сих пор?
           • Правильно ли указаны адреса и номера телефонов?
           • Уточняю другие факты, о которых говорится в тексте.

2. Представляю, что я пьяный читатель или читатель, который не в теме:
    2.1. Юзабилити:
           • Есть нечитабельные простыни текста?
           • Длинные абзацы?
           • Перечни, которые можно представить в виде списка?
           • Чересчур длинные списки?
    2.2. Содержание и стиль.
           • Остались ли недосказанности? Что-то неочевидное для непродвинутого пользователя?
           • Есть ли непонятные, непрозрачные предложения?
           • Есть ли отторжение от каких-то фраз? Что-нибудь, что может показаться неприятным, обидным?
    2.3. Картинки и схемы.
           • Везде ли их хватает?
           • Все ли на этих схемах понятно? Не нужно ли что-то дополнительно выделить или, наоборот, убрать лишние акценты?
           • Все ли оформлено по гайду?
           • Не изменился ли интерфейс за время вычитки?

3. Теперь я литературный редактор и правлю формулировки.
    Распечатываю текст. Читаю по бумажке: в идеале — вслух или хотя бы шепотом. Проверяю:
           • Соответствует ли стиль содержанию документа? Не выбивается ли что-то из общего стиля?
           • Есть ли предложения, которые можно упростить?
           • Канцелярские обороты?
           • Повторы однокоренных слов?
           • Режет ли что-то слух?
           • Есть ли речевые ошибки, смысловые неточности? Особенно это касается терминов, в правильности употребления которых я не уверена. Даже если термин в данном контексте слух не режет, лучше перепроверить.
           • Что с ритмом, с акцентами?

4. Я — корректор.
    Распечатываю текст еще раз. Проверяю:
           • пунктуацию,
           • орфографию, грамматику, опечатки,
           • типографику и теги.

5. Опять распечатываю, читаю чистовик.

6. Готовлю текст для автора. Проверяю комментарии к правкам.
           • Все ли понятно? Все ли неочевидные случаи я прокомментировала?
           • Если с какими-то правками переборщила — отклоняю.

7. Отправляю текст автору.

8. Согласовываем с автором правки, с которыми он не согласен. Автор переносит правки в текст.

9. Делаю финальную вычитку сверстанной версии.
          • Никаких правок не пропустили?
          • Не всплыли ли новые ошибки?
          • С версткой-переносами-заголовками-картинками все нормально?
          • Смотрю на общий вид страницы: все ли хорошо да красиво?

10. Если больше ничего не бесит, скорее всего, всё норм. Задачу на редактуру закрываем.

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

 

11 комментариев
о профессии,яндекс,личный опыт,Инструменты
Сжатие PNG без потерь
Алексей
17 февраля 2015, 19:06

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

Эту бесполезную часть можно автоматически отрезать, экономя до 30% объема (по нашему опыту).

Для этого предназначены следующие программы:

Длинно и по-английски

Технически исчерпывающе сжатие PNG без потерь описано здесь: http://optipng.sourceforge.net/pngtech/optipng.html

Коротко и по-русски

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

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

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

Пробный шар

Небольшая демонстрация — скриншоты одного из разделов нашей Помощи. Результат в ImageOptim — на 18,8 мегабайт картинок сэкономлено 4,7 мегабайт:

 

6 комментариев
иллюстрации,яндекс,Инструменты
Секция СПб сообщества техписателей на IT Global Meetup #4 в Петербурге
Salangin
25 февраля 2015, 18:19

Коллеги, мы ждем вас на IT Global Meetup #4 (27 февраля 2015, пятница) с 17 до 23.

Вся информация и регистрация на сайте митапа: piter-united.ru . Участие бесплатное

Программа секции на сайте сообщества tavtor.ru 

 

Нет комментариев
События,Санкт-Петербург,сообщество,2015,конференция
Нора Галь «Слово живое и мёртвое»
Татьяна Грачёва
26 февраля 2015, 13:32

Если вы еще не читали «Слово живое и мертвое» Норы Галь, очень рекомендую прочитать.

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

Книга наполовину состоит из примеров. Все они из реальной жизни: Нора Галь собирала их двадцать лет, в период расцвета советского языка — 50–70-е годы. Частично из-за обилия этих примеров, частично — из-за назидательного стиля и рыхлой структуры — книжку тяжеловато читать. Но именно эти примеры и делают эту книгу ценной.

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

Беда в том, что диктор произнес ни много ни мало: «Такие замены не способствуют пониманию вас вашими собеседниками»!!! Где же был редактор передачи? Почему не поправил хотя бы уж так: «Такие замены не помогают собеседникам вас понять»?

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

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

Канцелярский стиль делает текст сложным и неприятным. Его основные признаки:

  1. Вытеснение глагола причастием, деепричастием, отглагольным существительным. И из всех глагольных форм пристрастие к инфинитиву.
  2. Нагромождение существительных в косвенных падежах, чаще всего в родительном.
  3. Обилие иностранных слов там, где их можно заменить словами русскими.
  4. Вытеснение активных оборотов пассивными, почти всегда более тяжелыми, громоздкими.
  5. Тяжелый, путаный строй фразы. Несчетные придаточные предложения, неестественные в разговорной речи.
  6. Однообразие, стертость, штамп.
   

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

 

Как работать с этой книгой, чтобы получить максимум пользы

  • Читать первую главу («Берегись канцелярита!»). Остальная часть книги — о художественном переводе и интересна скорее для общего развития.
  • Использовать книгу как задачник. Почти все запутанные формулировки Нора Галь переводит на правильный русский: вы можете прочитать фразу на канцелярском, попробовать упростить ее самому, а затем свериться с правильным ответом. Я читала эту книгу именно так — прогресс был большой.
  • Держать эту книгу под рукой и время от времени к ней возвращаться. Это поможет вам быть в стилистическом тонусе и противостоять потоку окружающих нас штампов ))
9 комментариев
почитать,яндекс,стиль