Чем занимается технический писатель: опыт IT-компании Lad

Рассказывают технические писатели IT-компании Lad Екатерина Каляева, Анна Назолина, Ксения Скорынина

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

Технические писатели и knowledge management

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

Так выглядит база знаний Центра Разработки. Слева — проекты и дерево статей, справа — непосредственно тексты статей.

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

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

Технический писатель по канону

«Классический» технический писатель в компании занимается написанием не только внутренней документации на проекте, но и внешней — для заказчиков.

Внутренняя документация — это, например, описание админки, процесса продажи/возвратов/рассрочки, БД MongoDB. А внешняя обычно включает в себя описание верхнего уровня проекта: цели, требования, бизнес-эффект, а также мануал для работы сотрудников с разрабатываемым продуктом. Таким образом, технический писатель играет важную роль в команде вне зависимости от его специализации. Это не просто сотрудник, который пишет документацию, исходя из своей точки зрения и предпочтений. Техписатель-профессионал может почерпнуть «тайную» информацию от коллег-разработчиков и, что важно, принимает точку зрения каждого из коллег.

О том, почему документация — это непросто

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

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

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

Инструменты must-have

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

• Slack. С его помощью мы общаемся внутри нашей команды технических писателей и с членами других команд. Мессенджер удобен тем, что каждую новую тему в деталях можно обсудить в отдельном треде. Ребята из команд добавлены в каналы, соответствующие проектам. Это помогает быть в курсе новостей и обсуждений.
• Google Docs. Этот сервис мы используем, во-первых, чтобы продумать структуру статей или написать их целиком. Во-вторых, для написания технической документации верхнего уровня: мануала для заказчика, описания админки или для создания небольшого объема документации для коллег. Обычно даем доступ к нужному документу другому техническому писателю или коллеге в режиме редактирования, если он хочет добавить контент, или комментирования, если он готов проверить то, что мы написали.
• YouTrack. Его мы используем в двух случаях. Первый — это доска Agile, где мы пополняем наш бэклог, распределяем задачи между собой, отслеживаем прогресс. Второе — База знаний, куда мы выкладываем наши статьи и проводим ревью статьей от коллег.
• Confluence. Его преимущества — гибкость, большой выбор инструментов и древовидная структура, позволяющая сразу видеть новые проекты, релизы или требования. Инструменты Lucidchart и diagrams.net позволяют создавать широкий спектр диаграмм, от простых блок-схем до высокотехнологичных сетевых диаграмм, которые активно используют разработчики при переходе к новой функциональности на проекте.
• Технические писатели не остаются в стороне и от традиционно девелоперских инструментов. Так, для просмотра актуальных или выполненных задач мы используем issue-трекер в Gitlab. Там же читаем сам код, потому что иногда нам требуется описание полей и переменных. А с помощью MongoDB/Rancher можно посмотреть на используемые микросервисы, благодаря чему получается создавать более детальное описание.
• Последнее, о чем хотелось бы упомянуть, это сервисы Главред и Простым языком, где можно проверить качество своего текста, узнать, есть ли в нем повторы, опечатки, а также уменьшить его «водность».

Как выполнять план без нервов

Каждый день из работы технического писателя — особенный. Иногда мы несколько дней вдумчиво работаем над написанием одной статьи. А порой все горит и появляются новые задачи, которые нужно оперативно решать. Ежедневно мы проверяем доску Agile, оцениваем количество оставшихся задач и их статус. Выбрав приоритетные на день, прописываем их детально в карточке задачи, а затем переносим эти микрозадачи в свой Google-календарь. Так они удобно комбинируются с митингами и другими запланированными мероприятиями. Таким образом удается эффективно распределять свое время и не хвататься за все сразу, а план на день успешно выполняется.

Жизненные циклы задач

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

Задачи обычно приходят по нескольким каналам. В первую очередь, это техлид Центра Разработки или менеджер проекта. Мы практикуем регулярные встречи с ними, обычно в формате видеозвонка, чтобы обсудить прогресс по задачам: какие выполнены, какие сейчас в процессе, а что вызывает трудности. Другой путь формирования задач — это канал #docs в корпоративном мессенджере Slack. Мы используем его как инструмент коммуникации с командами: этой самый быстрый способ для них спросить технических писателей о чем-то или поручить написание статьи. В том же канале мы объявляем последний новости, связанные с базой знаний, и делаем анонсы статей.

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

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

3 сигнала, что задачу можно закрывать

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

1. SME или тот, кто ставил задачу, проверил текст статьи и посчитал, что мы отразили все детали вопроса.
2. Конечный текстовый продукт устраивает всех стейкхолдеров, которые работали над ним вместе с техписателями.
3. Если конкретного инициатора задачи нет или текст объемный, мы обычно тестируем его на нескольких представителях целевой аудитории. Если мы видим, что текст выполняет свою задачу для респондентов, значит, все получилось и задачу можно закрывать.

Следуя своей тактике, технические писатели IT-компании Lad за полгода обработали около 40 документационных задач и создали свыше 100 статей в базе знаний Центра Разработки.

Как думаете, на вашем месте работы пригодились бы технические писатели?