Как создаются шедевры: будни технического писателя

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

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

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

Как это устроено в «Оптимакрос»

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

Шаг первый: с чего начать?

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

• Что уже есть на эту тему? Это абсолютно новая документация или доработка существующей, что уже написано, есть ли какие-то материал?

• Кто является ответственным? Собираем контакты, кто отвечает за функционал, кто может предоставить информацию или направление, чтобы потом не искать источники информации самостоятельно;

• Для кого будет предназначаться эта документация? Разработчикам, администраторам и пользователям нужна разная информация, точнее, различная глубина и полнота информации.

Шаг второй: подготовка 

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

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

Шаг третий: много общаемся

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

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

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

Шаг четвертый: начинаем писать

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

Как писать? В соответствии с принятыми в компании стандартами. Если используется информационный стиль, следую ему, если допустимо использование мемов — применяю и этот подход. В какой программе работать? Здесь ориентируюсь на удобство. Я обычно создаю текст непосредственно в Confluence, поскольку там он будет храниться в итоге.

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

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

Шаг пятый: проверка

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

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

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

Шаг шестой: финальный

Итак, документация получила одобрение всех участников процесса, она тщательно проверена на наличие ошибок и соответствие техническому заданию. Что делать дальше?

В задаче отмечаем, что документация готова, прикрепляем ссылку на нее, отмечаем всех причастных, если это необходимо. Закрываем задачу и информируем всех заинтересованных лиц. Если это инструкция для пользователей, уведомляем службу технической поддержки, если внутренний документ — тех, кто будет им пользоваться. У нас сложилась традиция — сообщать в чат отдела о завершении работы над документацией, примерно так: «Документация готова, находится по этой ссылке, и не говорите потом, что вас не предупреждали».

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

В качестве заключения

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

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

Ну и, конечно, внерабочие активности: спорт, прогулки, путешествия. Основное правило — не оставаться в статичном положении после работы, чтобы рабочий процесс проходил комфортно и продуктивно.