Как мы в «Активе» пишем пользовательскую документацию. Почему это важно

[AndreyDmitriev]

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

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

Держать своего тех писателя в штате слишком накладно, поэтому документация аутсорсится в одну жаркую страну, где стоимость человекочаса втрое ниже, чем в головном офисе. Техписатель продукт в глаза не видел — ему надо хоть что-то выдать, поэтому менеджер начинает бурную деятельность — на очередном статус-митинге он просит начальника отдела разработки выдать хоть что-то техписателям. Отдел разработки занят следующим проектом, поэтому это дело делегируется в отдел тестирования (ну или техподдержки, но зачастую и этот отдел находится в той же самой жаркой стране, где и документация). Тестировщик открывает продукт и начинает жамкать по клавише Print Screen, иногда видит там опцию типа «Выб. пров.», которую он не помнит, тогда он отправляет в ms team (ну или скайп) сообщение «это чё такое?». Через полчаса от разраба ему прилетает «это опция Выборочная проверка», ну там не влезло, я сократил.

Тестировщик жамкает по клавише Print Screen ещё разок и пишет внизу «Выб. пров.» — Выборочная проверка", повторяет похожие действия для всех скриншотов и кладёт архив на сервер в папку проекта.

Техписатель загоняет все скриншоты в систему документации (кстати, там не всё так плохо), дописывает «Опция „Выб.пров“ предназначена для включения режима Выборочной Проверки. Вы можете активировать режим Выборочной Проверки при помощи путём установки флажка в поле „Выб.пров. Для деактивации режима Выборочной Проверки снимите флажок с опции Выб.пров.“, в результате чего оно раздувается на 25 страниц текста и выплёвывает pdf. Менеджер даже не открывает этот файл — он просто ставит галочку в графе „документация“ и все довольны (кроме конечного пользователя). Всё идёт по плану.

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

Вы, кстати, как локализацию документации на несколько языков делаете и в чём верстаете, если не секрет?

[Merseyside]

С первыми двумя абзацами трудно не согласиться, в 90% случаев так оно и есть. А дальше уже начинаются частности. Описанный пример относится к незрелым компаниям либо к тем, у кого продукт из b2c и он настолько прост, что никому и в голову не придёт вчитываться в документацию. Если компания посерьёзней и продукт посложнее (особенно если от него зависят деньги или безопасность), то и к документации требования другие, и процесс будет близок к тому, что описано в статье. А так да, «в мире реальном» есть куча примеров, когда нет ни аналитика, ни дизайнера, а разработчик выполняет ещё и функции тестировщика, девопса и техподдержки.

[Nastya_d]

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

[Chamellion]

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

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

[Nastya_d]

Спасибо! Да, вы правы, бывает несколько финальных итераций.

[Ar20L80]

Спасибо, Анастасия  за интересную публикацию. Знал о профессии "технический писатель", но даже не представлял что делает он делает. На одном из собеседований мне сказали: "Вы будете описывать простыми словами и в упрощенной форме продукцию компании для клиента и потребителей программ". То есть, получается - человек для связи с общественностью. Биржи контента, любого писателя имеющего техническое образование называют техническим писателем. Есть ли отличия в работе технического писателя в различных организациях и какой следующий этап карьеры у технического писателя?

[Nastya_d]

Благодарю за то, что читаете мои статьи, для меня это очень важно.

Большое количество людей о такой профессии даже не слышали.

Давайте отвечу на ваши вопросы:

1) Есть ли отличия в работе технического писателя в различных организациях?

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

2) Какой следующий этап карьеры у технического писателя?

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