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

Чек-лист редактора документации

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

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

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

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

Работаю в 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 комментариев
Ерохова Елена
28 января 2016, 03:16

Спасибо, отличный чек-лист.

Я бы дополнила опцией - проверка техническим редактором или тестировщиком.

В текстах, связанных с программными продуктами, содержащими инструкции, самое важное - проверка техническим редактором.

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

Не всегда, правда, это может сделать тот, кто пишет текст.

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

Татьяна Грачёва
28 января 2016, 03:16

Елена, да, согласна, инструкции надо проверять. Мы это делаем: идем по ссылкам, проверяем названия кнопок, проходим каждый шаг инструкции. 
В чек-листе это тоже есть: пункт 1.4 — там, где "продвинутый читатель" :)

Ерохова Елена
28 января 2016, 03:16

В случае пользовательского продукта, можно самому проверить.

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

 

Технический писатель может описать использование API, но попробовать - вряд ли. А это самая важная для пользователя часть документации.

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

Поэтому я бы поставила техническую редакцию как нулевой пункт, проверка исполнимости инструкций и примеров.

Если исполняется и можно применить, на опечатки можно закрыть глаза, но не наоборот.

Технический писатель может описать использование API, но попробовать - вряд ли.

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

Татьяна, здравствуйте.
А сколько раз по этому чек-листу приходится перечитывать текст?
Один первый пункт "Продвинутый читатель" содержит четыре крупных блока: суть, структура, ссылки и факты. Чтобы каждый проверить, вы перечитываете 4 раза? Или получается за один раз удержать в голове сразу несколько пунктов?
Интересен Ваш опыт в этом плане. Может быть есть какие-то методики?
Татьяна Грачёва
28 января 2016, 03:16
Егор, добрый день!

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

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

Если выделять минимальное количество подходов, которое необходимо выполнить при вычитке, я бы выделила четыре основных: вычитка структуры, проверка фактов (включая проверку инструкции), вычитка формулировок и корректура.

А методики я знаю только две: «послойная» вычитка (как тут) и «последовательная», когда редактор внимательно вычитывает предложение за предложением и никуда не возвращается. Сторонники последовательной вычитки считают, что при вычитке «слоями/подходами» пропускается много ошибок. Я с этим не согласна. У меня получается вычитывать качественнее именно слоями, потому что это дает мне возможность увидеть текст и целиком, и в деталях. Хотя, возможно, все зависит от особенностей мышления конкретного редактора.
Спасибо за ответ.
Мне тоже ближе послойная, тематическая вычетка. А лучше всего, конечно, когда твой текст вычитывает кто-то другой. Но такое редкость ). Единственное что помогает - это делать промежутки в несколько дней между написанием текста и его редактированием.
Татьяна Грачёва
28 января 2016, 03:16
Да, свежим взглядом посмотреть — это великая вещь. Мне тоже очень помогает.
Константин Молчанов
28 января 2016, 03:16

Что-то мне говорит, что Таня в школе была отличницей :-)

 

Пройти по такому чек-листу не каждый сможет, а уж написать — какая усидчивовать нужна!

Татьяна Грачёва
28 января 2016, 03:16
:D
Спасибо!